How to use this platform

Introduction

The AdmiralCloud Developer Platform combines live API references with integration guides for media management, metadata, search, processing, and delivery. This guide covers platform access, AdmiralCloud-specific API conventions, and the interactive request tools.

Quick start

Register for platform access.
Choose an authentication method for your integration and obtain the appropriate credentials and Client ID. See the Making authenticated requests article in the documentation after signing in.
Start with the Metadata Controller using curl or Try API, then continue with the relevant integration workflow.

Access to the Developer Platform requires registration. Register for access, or log in with an existing account.

This introductory guide is public and remains accessible before registration or login. For the full documentation, log in. The article and controller names below refer to content in that documentation; this public guide does not link directly to those pages.

The documentation session is separate from the credentials used by your integration or the Try API tool; platform access does not grant additional API permissions.

For questions about registration or access, contact your AdmiralCloud representative or support.

Find the right documentation

Documentation is organised by service and integration topic:

Section	Scope	Starting point after login
API Server	Media assets, containers, metadata, search, channels, and delivery	MediaContainer Controller
Auth Server	Authentication, sessions, and token management	PersonalAccessToken Controller
IAM Server	Users, permissions, and account context	Me Controller
Statistics	Usage and activity reporting	Statistic Controller
Event Service	Events for automated workflows	Upload-related events
Transcoding Service	Media processing	Image Metadata
Concepts	Data model and workflow explanations	Collections
Tutorials	Task-oriented integrations across multiple endpoints	Create collections with your favorites

The documentation search indexes page titles and section names, not fields or endpoint descriptions loaded from the live reference.

Read the live API reference

Controller pages combine a written introduction with a Reference section fetched directly from the corresponding API server. Use the live reference to verify the current endpoint contract when implementing examples from a tutorial.

Services and versions

The main API hosts are:

api.admiralcloud.com — core API operations.
auth.admiralcloud.com — authentication and token management.
iam.admiralcloud.com — identity and access management.
statistic.admiralcloud.com — statistics.

Versions are specific to services and controllers; there is no single version prefix to apply across all APIs. Use the method and versioned path documented for the individual operation. Generated curl examples include the corresponding host.

Request and response schemas

The Request Parameters table describes types, enum/range constraints, and requirements. An orange required badge marks mandatory fields; additional conditional requirements may appear in the description.

Nested properties are collapsed by default. Expand all exposes the full schema, including nested requirements that may not be populated in a generated request template.

The Response Fields table describes the returned structures. Field availability can depend on the operation, data, and permissions; consult field descriptions rather than treating an example response as a guaranteed shape.

Permissions and lifecycle notices

IAM Permissions Required lists endpoint-level and field-level requirements. Field-level badges identify restricted properties. These requirements apply independently of access to the developer documentation.

Endpoint and field notices identify deprecated, retired, beta, or experimental functionality. Consult the accompanying descriptions for restrictions and replacement endpoints.

Choose an authentication method

OAuth2 applications

For interactive applications, follow the OAuth2 flow in the Making authenticated requests article. Obtain a registered Client ID and configure the application's callback URL with AdmiralCloud.

Bearer-token requests use these headers:

Authorization: Bearer YOUR_TOKEN
x-admiralcloud-clientid: YOUR_CLIENT_ID
x-admiralcloud-device: YOUR_DEVICE_ID

Use the Client ID for your integration, not the developer website's own Client ID. If the session is bound to a device identifier, subsequent requests must use the same identifier.

Personal Access Tokens

The platform's Try API tool uses a Personal Access Token (PAT), independently of the OAuth2 session used to load the documentation. A PAT is not required simply to read the reference.

The PersonalAccessToken Controller reference documents token creation and management. The raw token is returned only once on creation and cannot be retrieved later. Try API accepts an existing PAT; it does not create tokens.

Server-to-server integrations

Backend integrations can use signed requests with an Access Key and Access Secret. The Making authenticated requests article describes the signing approach and links to libraries for Node.js, PHP, and Java.

Try API supports Bearer-token requests only; it does not generate request signatures. An Access Secret is not a PAT and must not be entered into the tool.

First request

The Metadata Controller provides access to asset metadata. This example uses the same endpoint shown on the home page:

curl --request GET 'https://api.admiralcloud.com/v5/metadata' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'x-admiralcloud-clientid: YOUR_CLIENT_ID' \
  --header 'x-admiralcloud-device: YOUR_DEVICE_ID'

Use credentials for the intended application and add any required request parameters according to the live reference. Access remains subject to the operation's IAM requirements.

Generated curl examples

Each endpoint's curl panel generates a request from the live schema. For GET and HEAD operations, parameters are encoded in the query string; other generated requests use a JSON body where request fields are available.

The generator has several important limitations:

Values are illustrative, not defaults. The generator may use the first enum value, a sample ID, an illustrative date, or an empty object or array.
Optional fields may be included. Remove fields that are not relevant to the operation you intend to perform.
Nested payloads may be incomplete. Required child properties must be supplied according to the expanded schema.

Treat the output as a template, not a validated request. Path parameters and credentials remain placeholders. A PAT saved in Try API is not inserted into copied curl commands.

Try API

Try API in the header configures credentials; Try beside an endpoint opens its request editor.

Requests are executed against the API server shown in the reference. This is not a sandbox or dry-run facility. Modifying operations affect real data; use an appropriate test account or designated test resources.

Credentials

Provide an existing Personal Access Token (the raw token, without the Bearer prefix) and the appropriate Client ID in Try API. The tool supplies a persistent browser Device ID, shown read-only in the dialog.

After Save, the header displays PAT active. This indicates that a token is stored, not that it has been validated. Authentication and permissions are checked by the API when a request is executed.

Request execution and limitations

The endpoint's Try panel provides an editable JSON template when request fields are documented. GET and HEAD parameters are entered as a JSON object and converted to query parameters; other methods use a JSON request body.

The editor checks JSON syntax but does not validate the complete schema or business rules. The generator limitations apply to this template too. Run request displays the HTTP status and response body.

Path parameters are not supported by the request editor. Endpoints with unresolved parameters such as :id cannot be executed from the panel. Use the generated curl command or another API client for these operations.

Credential storage

The PAT is stored in sessionStorage for the tab session. The Client ID and generated Device ID are stored in localStorage. Clear removes the stored PAT and Client ID, but retains the Device ID; it does not revoke the token on the server.

Logging out of the documentation does not clear the separately stored PAT. Use Clear to remove it, and the token-management endpoints when revocation is required.

Integration workflows

The following articles are available in the documentation after signing in:

File uploads: Uploading to AdmiralCloud and the S3 Controller. For external upload portals, see How to upload via Dropsite.
Asset search: ElasticSearch, the Search Controller, and Customized search experience.
Collections and favourites: Collections and Create collections with your favorites.
Metadata: Metadata Administration and the live references for the relevant metadata controllers.
Publishing and delivery: Links in AdmiralCloud and Creating Mediahubs.
Replacement and versioning: Replacement and Versioning.
Event-driven integrations: Administrative events, Upload-related events, and the Subscription Controller.

Troubleshooting

Live reference access

The reference is fetched using the documentation session, not the PAT configured in Try API. If access is denied, verify that your platform registration is complete and your documentation session is valid. A visible introduction does not confirm reference access: the static article and live schema have different data sources.

API request authorisation

Requests from Try API use the PAT, Client ID, and browser Device ID. For authorisation failures, check that context together with endpoint-level and field-level IAM requirements and access to the target resource. Registration for the Developer Platform does not change these permissions.

Generated payloads

For validation failures, compare the generated payload with the expanded request schema, particularly conditional requirements, nested properties, and enum/range constraints. The tool does not verify that generated sample values are valid for your account.

Browser request failures

If a request works in curl but fails in Try API, inspect the browser's network response for cross-origin restrictions or blocked requests. A network failure does not establish whether a modifying operation reached the server; verify the resource state before retrying.

Support

For questions about registration, access, or your integration, contact your AdmiralCloud representative or use the support form.

For API issues, include the documentation URL, API host, method and path, HTTP status, error response, and request time with time zone. Include a request identifier if returned by the API, and indicate whether the issue occurs in Try API, curl, or your integration. Redact credentials and confidential data from any examples.