Hardata API

Document version: 1.1
Contrato fuente: OpenAPI 3.1.1, API v1.0
Reference status: September 14, 2026

This is the public, self-contained HARDATA API reference. It supports authentication, querying and management of media, metadata, catalogs, and advertising traffic, as well as execution of the scheduling algorithm. It should be used together with HARDATA ECP when an application also needs to monitor or control HDX in real time.

This documentation does not contain tokens, keys, users, passwords, or private values from any installation. All authentication values in the examples are placeholders that the integrator must replace at runtime.

1. Base URL and Transport

The reference specification declares http://localhost:5010/. In a real installation, the base URL is provided by HARDATA or by the system administrator. Do not hard-code localhost or a port as product constants.

• Transporte HTTP/HTTPS.
• JSON bodies are UTF-8 except for multipart/form-data and media streaming.
• Dates and times must be sent in the format specified by each field's schema.
• Identifiers are opaque: do not infer meaning, order, or persistence from their value. When the schema declares int64, its decimal representation is still an identifier, not a number suitable for business calculations.
• Use HTTPS in production and validate the certificate.

2. Authentication

The specification declares HTTP Bearer authentication using JWT tokens. Obtain a token with POST /api/v1/auth/login and send it with protected requests:

Authorization: Bearer <token-jwt>

Login example without real credentials:

POST /api/v1/auth/login
Content-Type: application/json

{ "username": "<usuario>", "password": "<contraseña>" }

Response: LoginResponse, with success, message, token and refreshToken. When the token has expired, refresh it with POST /api/v1/auth/refresh. Never log the login body or token. The OpenAPI source defines the Bearer scheme but does not annotate security operation by operation; an integration should treat any endpoint not explicitly exposed as public by the installation as protected and handle 401 Unauthorized.

The HARDATA API base URL, credentials, and token are configured and managed separately from the HARDATA ECP connection. An authenticated WebSocket session does not authenticate HTTP requests, session.setup does not discover the API, and an App must not assume that both services share credentials even if a particular installation has provisioned them that way.

3. Client Conventions

• Send Accept: application/json for JSON responses.
• Send Content-Type: application/json for JSON creates and updates.
• Tratar 200 and 201 as success with a body; 204 as success without a body.
• Handle 400 as invalid input, 401 as missing or expired authentication, 404 as resource not found, 409 as a conflict, and 500 as an internal server error.
• For errors with a body ProblemDetails, preserve status, title, detail, type e instance.
• Do not automatically retry POST, PUT o DELETE if the outcome is unknown. Check the resource state first.
• Apply timeouts, cancellation, and backoff with jitter. Refresh the token according to the installation policy.
• Allow additional properties to maintain compatibility with future extensions.

Relationship of materialId with HARDATA ECP

materialId is an Int64 in HARDATA Database and HARDATA API. HARDATA ECP transports it as a canonical decimal string to avoid loss of precision: 0 or a sequence without a leading zero between 1 and 9223372036854775807.

To query the metadata of an ECP node, the App uses that sequence literally as {materialId} in GET /api/v1/material/{materialId}. The server converts it to Int64 using invariant culture. It must not first be converted to Number in JavaScript; to read JSON responses containing int64 outside JavaScript's safe range, a parser that preserves 64-bit integers is required.

4. Minimal Examples

Query a media item

GET /api/v1/material/12345
Authorization: Bearer <token-jwt>
Accept: application/json

Query Timing for Automation

Use GET /api/v1/material/{materialId}. The integer time fields of MaterialResponse are expressed in milliseconds:

• startPos and endPos: start and end positions on the file timeline; endPos = 0 indicates that the physical end is used.
• punchIn e intro: positions measured from the beginning of the file.
• punchOut and outro: offsets measured backward from the effective end; for example, punchOut = 1500 starts the crossfade when 1500 ms remain.
• punchInFadeLength and punchOutFadeLength: fade durations.
• insertOver: time offset, also in milliseconds.

An application such as AI Operator can combine this metadata with positionMs, durationMs and remainingMs received through HARDATA ECP. HARDATA API does not replace ECP timers or playback events; before comparing values, the App must respect the direction of each marker and use a single unit.

Paginated Search

GET /api/v1/material/search?q=nombre&page=1&pageSize=50
Authorization: Bearer <token-jwt>

Streaming with Seeking

GET /api/v1/material/12345/stream?fileId=67890
Authorization: Bearer <token-jwt>
Range: bytes=0-1048575

The endpoint may return 200 or 206; handle 416 when the requested range is invalid.

5. Complete Endpoint Catalog

Agency

GET /api/v1/traffic/agency

POST /api/v1/traffic/agency

Cuerpo: CreateAgencyRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

GET /api/v1/traffic/agency/{agencyId}

PUT /api/v1/traffic/agency/{agencyId}

Cuerpo: UpdateAgencyRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

DELETE /api/v1/traffic/agency/{agencyId}

GET /api/v1/traffic/agency/types

GET /api/v1/traffic/agency/statuses

Album

GET /api/v1/album

POST /api/v1/album

Cuerpo: CreateAlbumRequest. Content-Type: application/json, application/*+json. Required: yes.

GET /api/v1/album/{id}

PUT /api/v1/album/{id}

Cuerpo: UpdateAlbumRequest. Content-Type: application/json, application/*+json. Required: yes.

DELETE /api/v1/album/{id}

Algorithm

POST /api/v1/traffic/algorithm/schedule

Execute the scheduling algorithm for a specific date and station.

Cuerpo: ScheduleRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

GET /api/v1/traffic/algorithm/stats

Get scheduling statistics for a specific date and station. Useful for preview before running the full algorithm.

AssetType

GET /api/v1/asset-type

GET /api/v1/asset-type/{assetTypeId}

Auth

POST /api/v1/auth/login

Cuerpo: HdxLoginRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

POST /api/v1/auth/refresh

Cuerpo: RefreshTokenRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

Break Templates

GET /api/v1/traffic/breaktemplate

List all templates

POST /api/v1/traffic/breaktemplate

Cuerpo: CreateBreakTemplateRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

GET /api/v1/traffic/breaktemplate/{id}

PUT /api/v1/traffic/breaktemplate/{id}

Cuerpo: UpdateBreakTemplateRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

DELETE /api/v1/traffic/breaktemplate/{id}

GET /api/v1/traffic/breaktemplate/station/{stationId}

Get templates by station

DELETE /api/v1/traffic/breaktemplate/{id}/hard

BreakType

GET /api/v1/traffic/break-types

POST /api/v1/traffic/break-types

Cuerpo: CreateBreakTypeRequest. Content-Type: application/json, application/*+json. Required: yes.

PUT /api/v1/traffic/break-types/{id}

Cuerpo: UpdateBreakTypeRequest. Content-Type: application/json, application/*+json. Required: yes.

DELETE /api/v1/traffic/break-types/{id}

Campaign

GET /api/v1/traffic/campaign

POST /api/v1/traffic/campaign

Cuerpo: CreateCampaignRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

GET /api/v1/traffic/campaign/{campaignId}

PUT /api/v1/traffic/campaign/{campaignId}

Cuerpo: UpdateCampaignRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

DELETE /api/v1/traffic/campaign/{campaignId}

GET /api/v1/traffic/campaign/statuses

Category

GET /api/v1/category

POST /api/v1/category

Cuerpo: CreateCategoryRequest. Content-Type: application/json, application/*+json. Required: yes.

GET /api/v1/category/{categoryId}

PUT /api/v1/category/{categoryId}

Cuerpo: UpdateCategoryRequest. Content-Type: application/json, application/*+json. Required: yes.

DELETE /api/v1/category/{categoryId}

GET /api/v1/category/storages

GET /api/v1/category/{categoryId}/nextcode

GET /api/v1/category/{categoryId}/children

GET /api/v1/category/{categoryId}/ancestors

GET /api/v1/category/{categoryId}/descendants

Client

GET /api/v1/traffic/client

Gets all clients.

POST /api/v1/traffic/client

Creates a new client.

Cuerpo: CreateClientRequest. Content-Type: application/json, application/*+json. Required: yes.

GET /api/v1/traffic/client/{clientId}

Gets a client by ID.

PUT /api/v1/traffic/client/{clientId}

Updates an existing client.

Cuerpo: UpdateClientRequest. Content-Type: application/json, application/*+json. Required: yes.

DELETE /api/v1/traffic/client/{clientId}

Deletes a client by ID.

GET /api/v1/traffic/client/statuses

Clip Metadata

GET /api/v1/traffic/clip_metadata

POST /api/v1/traffic/clip_metadata

Cuerpo: CreateClipMetadataRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

GET /api/v1/traffic/clip_metadata/{clipMetadataId}

DELETE /api/v1/traffic/clip_metadata/{clipMetadataId}

Common

GET /api/v1/traffic/common/scopes

Possible scopes (National / Local). Used in Order, BreakTemplateZone, and ClipMetadata.

GET /api/v1/traffic/common/weekdays

Base values for the day-of-week bitmask. Used in OrderDaypart and BreakTemplate.

GET /api/v1/traffic/common/break-types

Available break types (Simple, Rotating, etc.). Used in BreakTemplate.

Company

GET /api/v1/company

POST /api/v1/company

Cuerpo: CreateCompanyRequest. Content-Type: application/json, application/*+json. Required: yes.

GET /api/v1/company/{companyId}

PUT /api/v1/company/{companyId}

Cuerpo: UpdateCompanyRequest. Content-Type: application/json, application/*+json. Required: yes.

DELETE /api/v1/company/{companyId}

FileType

GET /api/v1/file-type

GET /api/v1/file-type/{fileTypeId}

Genre

GET /api/v1/genre

POST /api/v1/genre

Cuerpo: CreateGenreRequest. Content-Type: application/json, application/*+json. Required: yes.

GET /api/v1/genre/{id}

PUT /api/v1/genre/{id}

Cuerpo: UpdateGenreRequest. Content-Type: application/json, application/*+json. Required: yes.

DELETE /api/v1/genre/{id}

Industry

GET /api/v1/traffic/industry

Gets all industries.

POST /api/v1/traffic/industry

Creates new industries.

Cuerpo: array of string. Content-Type: application/json, text/json, application/*+json. Required: yes.

GET /api/v1/traffic/industry/{industryId}

Gets a specific industry by ID.

PUT /api/v1/traffic/industry/{industryId}

Updates an existing industry.

Cuerpo: UpdateIndustryRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

DELETE /api/v1/traffic/industry/{industryId}

Deletes an existing industry.

Media

GET /api/v1/material

Gets all media, with optional filters and pagination. Each CATEGORYMATERIAL row (master or link) is returned as a media item. By default, the recycle bin is excluded (isDeleted=false).

GET /api/v1/material/search

Searches media by free text across all relevant fields (title, code, comments, rdsText, tags, customFields, artist/author names, album, genre, company).

GET /api/v1/material/{materialId}

Gets a media item by ID.

PUT /api/v1/material/{materialId}

Updates the metadata of an existing media item.

Cuerpo: UpdateMaterialRequest. Content-Type: application/json, application/*+json. Required: yes.

DELETE /api/v1/material/{materialId}

Deletes an entire media item: physical files, MATERIALFILE, FILE, CATEGORYMATERIAL, and finally MATERIAL. Sequential order is used to respect foreign keys.

GET /api/v1/material/{materialId}/stream

Audio/video stream for frontend playback. Supports range requests for seeking.

POST /api/v1/material/placeholder

Creates a placeholder media item without audio.

Cuerpo: MaterialPlaceholderRequest. Content-Type: application/json, application/*+json. Required: yes.

GET /api/v1/material/{materialId}/files

Gets all files associated with a media item.

PUT /api/v1/material/{materialId}/category/{categoryId}

Moves a media item to another category. Replaces all existing category links.

DELETE /api/v1/material/{materialId}/files/{fileId}

Deletes a file associated with a media item, including the physical file from storage.

POST /api/v1/material/batch-delete

Deletes multiple media items in a single sequential transaction to avoid deadlocks.

Cuerpo: BatchDeleteRequest. Content-Type: application/json, application/*+json. Required: yes.

POST /api/v1/material/fill

Attaches an audio or video file to an existing media item.

Cuerpo: multipart/form-data. Required: yes.

GET /api/v1/material/{materialId}/artists

POST /api/v1/material/{materialId}/artists

Cuerpo: LinkArtistRequest. Content-Type: application/json, application/*+json. Required: yes.

DELETE /api/v1/material/{materialId}/artists/{personId}

GET /api/v1/material/{materialId}/authors

POST /api/v1/material/{materialId}/authors

Cuerpo: LinkAuthorRequest. Content-Type: application/json, application/*+json. Required: yes.

DELETE /api/v1/material/{materialId}/authors/{personId}

MediaType

GET /api/v1/media-type

GET /api/v1/media-type/{mediaTypeId}

Order

GET /api/v1/traffic/order

POST /api/v1/traffic/order

Cuerpo: CreateOrderRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

GET /api/v1/traffic/order/{orderId}

PUT /api/v1/traffic/order/{orderId}

Cuerpo: UpdateOrderRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

DELETE /api/v1/traffic/order/{orderId}

GET /api/v1/traffic/order/statuses

GET /api/v1/traffic/order/position-types

GET /api/v1/traffic/order/protection-levels

Order Daypart

GET /api/v1/traffic/order_daypart

POST /api/v1/traffic/order_daypart

Cuerpo: CreateOrderDaypartRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

GET /api/v1/traffic/order_daypart/{id}

PUT /api/v1/traffic/order_daypart/{id}

Cuerpo: UpdateOrderDaypartRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

DELETE /api/v1/traffic/order_daypart/{id}

Person

GET /api/v1/person

POST /api/v1/person

Cuerpo: CreatePersonRequest. Content-Type: application/json, application/*+json. Required: yes.

GET /api/v1/person/{id}

PUT /api/v1/person/{id}

Cuerpo: UpdatePersonRequest. Content-Type: application/json, application/*+json. Required: yes.

DELETE /api/v1/person/{id}

PGM5

GET /api/v1/traffic/pgm5/all

GET /api/v1/traffic/pgm5/{pgmId}

DELETE /api/v1/traffic/pgm5/{pgmId}

GET /api/v1/traffic/pgm5

POST /api/v1/traffic/pgm5

Cuerpo: SavePgm5Request. Content-Type: application/json, text/json, application/*+json. Required: yes.

GET /api/v1/traffic/pgm5/exists

PATCH /api/v1/traffic/pgm5/{pgmId}/status

Cuerpo: UpdatePgm5StatusRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

PGM

GET /api/v1/pgm

POST /api/v1/pgm

Cuerpo: CreatePgmRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

GET /api/v1/pgm/types

GET /api/v1/pgm/conditions

GET /api/v1/pgm/{pgmId}

PUT /api/v1/pgm/{pgmId}

Cuerpo: UpdatePgmRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

DELETE /api/v1/pgm/{pgmId}

PriorityType

GET /api/v1/priority-type

GET /api/v1/priority-type/{priorityTypeId}

Report

GET /api/v1/traffic/reports/programming

GET /api/v1/traffic/reports/orders

GET /api/v1/traffic/reports/schedule

GET /api/v1/traffic/reports/break-occupancy

GET /api/v1/traffic/reports/industry-share

GET /api/v1/traffic/reports/audit

RythmType

GET /api/v1/rythm-type

GET /api/v1/rythm-type/{rythmTypeId}

Settings

GET /api/v1/traffic/settings

PATCH /api/v1/traffic/settings

Cuerpo: UpdateSettingsRequest. Content-Type: application/json, application/*+json. Required: yes.

Station

GET /api/v1/station

Get all stations

GET /api/v1/station/{stationId}

Get station by ID

Template

GET /api/v1/traffic/template

POST /api/v1/traffic/template

Cuerpo: CreateTemplateRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

GET /api/v1/traffic/template/{id}

PUT /api/v1/traffic/template/{id}

Cuerpo: UpdateTemplateRequest. Content-Type: application/json, text/json, application/*+json. Required: yes.

DELETE /api/v1/traffic/template/{id}

DELETE /api/v1/traffic/template/{id}/hard

User

POST /api/v1/traffic/user/refreshusers

GET /api/v1/traffic/users

Gets all users.

GET /api/v1/traffic/user/{userid}

Gets a user by ID.

PUT /api/v1/traffic/user/{userid}

Updates a user's roleid (singular endpoint).

Cuerpo: UpdateUserRoleDto. Content-Type: application/json, text/json, application/*+json. Required: yes.

PUT /api/v1/traffic/users/{userid}

Updates a user's roleid (plural endpoint).

Cuerpo: UpdateUserRoleDto. Content-Type: application/json, text/json, application/*+json. Required: yes.

6. Data Models

The following names and types are derived directly from the OpenAPI contract. A property not marked as required may be absent; in addition, some legacy models allow null values even when the schema does not always mark them explicitly. Clients should deserialize tolerantly.

Model ActiveStage

Active stage of the scheduler. Controls which logic is enabled.

Model AgencyResponse

Model AlbumResponse

Model AssetTypeResponse

Model BatchDeleteRequest

Model BreakClipResponse

Clip fijo pre-asignado.

Model BreakResponse

Information about a scheduled break.

Model BreakTemplateClipResponse

Response DTO for a template clip.

Model BreakTemplateResponse

Response DTO for a break template.

Model BreakTemplateZoneResponse

Response DTO for a template zone.

Model CampaignResponse

Model CategoryResponse

Model ClientResponse

Model ClipMetadataResponse

Model ClipRequest

Model ClipResponse

Model CompanyResponse

Model CreateAgencyRequest

Model CreateAlbumRequest

Model CreateBreakTemplateClipRequest

DTO for creating a clip within a template.

Model CreateBreakTemplateRequest

DTO for creating a new break template. Includes associated zones and clips.

Model CreateBreakTemplateZoneRequest

DTO for creating a zone within a template.

Model CreateBreakTypeRequest

Model CreateCampaignRequest

Model CreateCategoryRequest

Model CreateClientRequest

Model CreateClipMetadataRequest

Model CreateCompanyRequest

Model CreateGenreRequest

Model CreateOrderDaypartRequest

Model CreateOrderRequest

Model CreatePersonRequest

Model CreatePgmRequest

Model CreateTemplateRequest

Model FileTypeResponse

Model GenreResponse

Model HdxLoginRequest

Model IFormFile

Model IndustryItem

Model IndustryResponse

Model LinkArtistRequest

Model LinkAuthorRequest

Model LoginResponse

Model MaterialArtistResponse

Model MaterialAuthorResponse

Model MaterialFileResponse

Model MaterialFillResponse

Model MaterialPlaceholderRequest

Model MaterialResponse

Model MediaTypeResponse

Model NextCodeResponse

Model OrderDaypartDto

Model OrderResponse

Model PagedResponseOfMaterialResponse

Model PersonResponse

Model Pgm5ExistsResponse

Model Pgm5SummaryResponse

Model PgmBlockRequest

Model PgmBlockResponse

Model PgmConditionResponse

Model PgmEventRequest

Model PgmEventResponse

Model PgmResponse

Model PriorityTypeResponse

Model ProblemDetails

Model ProgrammingTypeResponse

Model RefreshTokenRequest

Model ReportAuditLogItem

Audit row for user actions.

Model ReportBreakOccupancyItem

Average break occupancy by hour within the range.

Model ReportIndustryShareItem

Share by industry within the range.

Model ReportOrdenesItem

Projected airings by order over a date range.

Model ReportScheduleItem

As-run log: one row per media playout (spot or clip) within the range.

Model RythmTypeResponse

Model SaveBreakClipRequest

Model SaveBreakRequest

Model SavePgm5Request

Model SavePgm5Response

Model SaveSpotRequest

Model SaveUnplacedRequest

Model SaveZoneRequest

Model ScheduleRequest

Request to execute the scheduling algorithm.

Model SchedulingMetricsResponse

Result metrics.

Model SchedulingResponse

Hierarchical response from the scheduling algorithm. Structure: Breaks → Zones → Spots

Model SchedulingStats

Statistics about scheduling availability for a date.

Model SchedulingSummary

Overall result summary.

Model Scope

Scope of a spot or zone: National or Local.

Model ScoreWeights

Weights used to calculate candidate scores in the algorithm scoring.

Model SettingsResponse

Model SpotResponse

Assigned spot (commercial/imaging).

Model TemplateBreakTemplateSummaryResponse

Model TemplateResponse

Model UnplacedResponse

Spot that could not be assigned.

Model UpdateAgencyRequest

Model UpdateAlbumRequest

Model UpdateBreakTemplateRequest

DTO for updating an existing template.

Model UpdateBreakTypeRequest

Model UpdateCampaignRequest

Model UpdateCategoryRequest

Model UpdateClientRequest

Model UpdateCompanyRequest

Model UpdateGenreRequest

Model UpdateIndustryRequest

Model UpdateMaterialRequest

Model UpdateOrderDaypartRequest

Model UpdateOrderRequest

Model UpdatePersonRequest

Model UpdatePgm5StatusRequest

Model UpdatePgmRequest

Model UpdateSettingsRequest

Model UpdateTemplateRequest

Model UpdateUserRoleDto

Model ZoneResponse

Zone within a break.

7. Flujos recomendados

On-Air Assistance Application

1. Authenticate and keep the token out of logs.
2. Use HARDATA ECP to obtain playlists, playlistItemId, materialId, timers, and current/next changes.
3. Query GET /api/v1/material/{materialId} for metadata and audio markers.
4. Query artists and authors through the endpoints associated with the media item when needed.
5. Cache responses by materialId, with reasonable invalidation; do not query on every timer event.
6. Make transport decisions exclusively from the authoritative HARDATA ECP state.

Traffic Management

1. Create or query agencies, clients, campaigns, and orders.
2. Configure dayparts, clips, industries, priorities, and constraints.
3. Configure templates and break templates by station.
4. Query algorithm statistics.
5. Run scheduling and review conflicts, unplaced items, and metrics.

8. Security and Privacy

• Do not include users, passwords, JWTs, keys, or private URLs in source code, repositories, telemetry, or screenshots.
• Store secrets in the operating system's secure store or in a secrets manager.
• Avoid logging bodies that may contain personal data, contacts, emails, or tokens.
• Apply least privilege and separate read-only accounts from accounts with modification or deletion capabilities.
• Explicitly confirm destructive operations, especially hard delete, batch delete, and deletion of physical files.
• Do not expose the WebSocket broadcast endpoint to users without administrative authorization.

9. Implementation Checklist

• Configurable base URL and HTTPS in production.
• Login and token kept out of logs.
• Bearer sent only to the expected host.
• Timeouts, cancellation, and backoff implemented.
• 200, 201, 204, 206, 400, 401, 404, 409, 416 and 500 manejados.
• Pagination applied to media listings.
• Streaming implementa Range requests.
• Unknown mutations are not automatically retried.
• Physical deletions require confirmation.
• Models tolerate additional and null fields.
• HARDATA ECP is used as the authority for on-air state.