API Quickstart

In this section, you'll find a step-by-step guide to quickly start using the Ariel APIs.

Prerequisites

Before you start, please make sure you have the following:

An authentication account on our platform

Authentication

Our API endpoints sit behind authentication. This means you'll need to obtain an access token to authenticate your requests. Please see authentication for base URLs.

Here's how you can do this:

Register your application with our platform to obtain your client credentials.
Send a POST request to our authentication endpoint with your client credentials to obtain an access token.

The request should look something like this:

POST /v2/as/token.oauth2 HTTP/1.1
Host: cp-auth.maestro.twdc.com
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials&scope=RETURN_ALL_CLIENT_SCOPES

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual client ID and client secret. The server will respond with an access token.

The response will look something like this:

Sample CURL Request:

curl --location 'https://cp-auth.maestro.twdc.com/v2/as/token.oauth2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=YOUR_CLIENT_ID' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
--data-urlencode 'scope=RETURN_ALL_CLIENT_SCOPES' \
--data-urlencode 'grant_type=client_credentials'

Response:

{
"access_token": "YOUR_ACCESS_TOKEN",
"token_type": "Bearer",
"expires_in": 3600
}

Include this access token in the Authorization header of your API requests. The header should look something like this:

Authorization: Bearer YOUR_ACCESS_TOKEN

Remember to securely store your client credentials and access token, and never share them publicly.

Making Your First Request

Once you have your access token, you can make your first request to our API. Let's start with a simple GET request to obtain characters.

Here's an example of how to make this request:

GET /v1/jobs/{entityId}/orders/{orderId}/characters HTTP/1.1
Host: _TBD_
Authorization: Bearer YOUR_ACCESS_TOKEN

The server will respond with a JSON object containing the character information.

Here's an example of a typical response:

{
  "data": [
    {
      "characterId": "752af4e0-5edd-4ea0-a53d-637b2b3a7123",
      "characterName": "Mickey Mouse",
      "sourceSystem": "manual"
    },
    {
      "characterName": "Angela Montenegro",
      "sourceSystem": "ctam"
    }
  ],
  "meta": {
    "query": "jobId=d2545f30-50d0-48fd-8e73-aa689999061f&orderId=7ed1a0e6-6f9d-43b6-9d1a-df0ba7c2c5bc",
    "pageNumber": 1,
    "totalElements": 2,
    "limit": 0,
    "offset": 0
  }
}

Response Handling

When you make a request to the API, the response will contain a status code, headers, and a body. Here's how to interpret these components:

Status Codes

The status code indicates the result of the request.

Common status codes include:

200 OK: The request was successful, and the response contains the requested data.
201 Created: The request was successful, and a new resource was created.
204 No Content: The request was successful, but there is no content to return.
400 Bad Request: The request was invalid or cannot be otherwise served.
401 Unauthorized: Authentication failed or user does not have permissions for the requested operation.
403 Forbidden: The server understood the request, but it refuses to authorize it.
404 Not Found: The requested resource could not be found.
409 Conflict: The request could not be completed due to a conflict with the current state of the target resource.
429 Too Many Requests: Too many requests were sent in a given amount of time.
500 Internal Server Error: An error occurred on the server while processing the request.

Error Handling

If the API returns an error, then the response will include an error code.

When you receive an error response, check the error code to determine the cause of the error. Common error codes can be found in the documentation Status Codes.

API Usage Tips

Here are some tips to help you use our API effectively:

Use the correct HTTP methods: Each endpoint in our API is designed to respond to a specific HTTP method. Make sure you're using the correct method (GET, POST, PUT, DELETE, etc.) for each request.
Handle pagination: If an endpoint returns a large amount of data, the response may be paginated. Check the response headers or body for pagination links or tokens.
Rate limiting: Be aware of the rate limiting policies of our API. If you make too many requests in a short period of time, your requests may be throttled.
Error handling: Always check the HTTP status code and error messages returned by the API. This will help you understand what went wrong when a request fails.
Use filters and query parameters: Many endpoints support filters and query parameters that can help you narrow down the data you're retrieving.
Keep your access tokens secure: Your access tokens are like passwords. Keep them secure and don't share them.
Use the correct content type: When sending data to the API, make sure you're setting the Content-Type header correctly and that the body of your request matches that content type.
Stay updated: We regularly update our API with new features and improvements. Check our API documentation regularly to stay updated.

Next Steps

Now that you've made your first request to our API and learned how to handle the responses, you're ready to explore further. Here are some next steps you might consider:

Explore More Endpoints: Our API has many more endpoints that you can use to interact with our platform. Check out our API Reference for a complete list of endpoints and their functionalities.
Integrate the API into Your Application: Start integrating our API into your application. Use the access token to authenticate your requests and use the endpoints to perform actions.
Handle Errors and Edge Cases: Learn how to handle different types of errors and edge cases in your application. This includes invalid requests, server errors, and rate limiting.

21 August 2025