Skip to content

API overview

The Opaque API follows standard RESTful conventions and is fully described using the OpenAPI Specification. It provides access to resources and operations via specific endpoints, using standard HTTP methods and response codes. Requests and responses are formatted in JSON.

Note

All available endpoints are documented in the Opaque API reference.

API structure

To interact with the API, follow these principles:

  • Use the appropriate HTTP method (GET, POST, PUT, PATCH, DELETE).
  • Identify the correct endpoint and resource path.
  • Include the necessary authentication and request parameters.

For detailed examples and endpoint-specific guidance, refer to the API reference.

HTTP method

The API is structured around resources (e.g., workspaces, datasets, jobs) that can be retrieved, created, updated, or deleted using standard HTTP methods:

  • GET: Retrieve resources
  • POST: Create new resources
  • PUT/PATCH: Update existing resources
  • DELETE: Remove resources

These methods enable CRUD (Create, Read, Update, Delete) operations on API resources.

Endpoint structure

Endpoints in the Opaque API follow a consistent format:

  • Base URL: The API is hosted at: https://<subdomain>-api.<domain>.
  • Resource path: Paths start with the API version (e.g., /v1.0/) and include one or more resource identifiers. Specific resources are referenced using a universally unique identifier (UUID).

Example

The following endpoint creates a job for a given workspace.

POST https://<subdomain>-api.<domain>/{version}/workspace/{workspace-uuid}/job

Path parameters:

  • {version}: The API version (e.g., v1.0)
  • {workspace-uuid}: The unique identifier for the workspace

Request headers

API requests require specific headers to define authentication, request format, and response format:

  • Authentication:
    • Include your API token in the Authorization header. For example, Authorization: Bearer <your_api_token>.See Authentication for details.
  • Content-Type:
    • application/json: Used for most requests with a JSON body.
    • multipart/form-data: Required for file uploads.
  • Accept:
    • application/json: For JSON responses.
    • text/plain: For plain text responses (e.g., logs).

Body parameters

Many API endpoints require a JSON request body and return a JSON response body:

  • Request body: Required for most POST, PUT, and PATCH operations.
  • Response body: Typically includes detailed information about the resource. DELETE requests usually return headers without a response body.

Refer to the API reference for the required body parameters and mandatory fields for each endpoint.

Interacting with the API

Before making API requests, ensure you have a valid API token and the correct base URL. All requests must be made over HTTPS; requests over plain HTTP or without valid authentication will result in errors.

You can interact with the API using:

  • curl (command-line tool)
  • Postman (API testing tool)

To get started, retrieve your API token and key. Once authenticated, you can begin making API calls.

For a full list of available endpoints, examples, and best practices, see the API reference.