API Reference

Access detailed reference documentation for Amondo's API endpoints.

Overview

Amondo provides a GraphQL Public API to work with Amondo entities programmatically. The same API is used internally by our team to power the Amondo platform, so external developers have full access to the same capabilities.

If you are new to GraphQL, we recommend reviewing the official GraphQL documentation to get familiar with queries, mutations, and schema design.

With this API you can:

• Query published Imprints

• Manage Collections, Tiles and Frames

• Authenticate and manage user sessions

• Access analytics and metadata (where available)

Endpoints

Amondo provides two GraphQL endpoints:

Standard API (full access):

https://gql.amondo.com

Cached API (read-only, optimised for published Imprints):

https://gql-public.amondo.com

Use the cached API for requests that fetch published content (e.g. query ImprintPublication), to improve performance and reduce load on the main endpoint.

All requests must be made over HTTPS.

Authentication

Amondo uses OAuth 2.0 for authentication. Every request must include a valid bearer token in the Authorization header:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  --data '{ "query": "{ me { id teams } }" }' \
  https://gql.amondo.com

The only auth-less operations are:

• query ImprintPublication

• mutation Login

• mutation submitQuizResults

Getting access

To use the API, you will need valid login credentials for an Amondo account. API access is currently provisioned as part of an Amondo platform subscription.

1. Contact your Amondo account manager or support team to request developer access.

2. You will be provided with a user email and password.

3. Use these credentials with the mutation login call to retrieve your API token.

If you need to rotate or revoke access, please contact Amondo support.

Getting a token

Tokens are retrieved using the mutation login mutation with your user email and password.

Example request:

mutation {
  login(email: "[email protected]", password: "secret") {
    token
    user {
      id
      email
    }
  }
}

Example response:

{
  "data": {
    "login": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "user": {
        "id": "12345",
        "email": "[email protected]"
      }
    }
  }
}

Use the returned token in the Authorization header for all subsequent requests.

Queries

Below is a list of key queries available in the API. For the full schema, use the GraphQL introspection query.

ImprintPublication (public, cached)

Fetches details of a published Imprint.

Example request:

query {
  imprintPublication(id: "abc123") {
    id
    imprint {
      id
      status
    }
  }
}

Example response:

{
  "data": {
    "imprintPublication": {
      "id": "abc123",
      "imprint": {
        "id": "abc",
        "status": "ACTIVE"
      }
    }
  }
}

Other queries

• collection(id: ID) → Fetch details of a Collection

• tile(id: ID) → Fetch details of a Tile

Mutations are used to create, update or delete entities.

createTile

Creates a new Tile in a Collection.

Example request:

mutation {
  createTextTile(data: {
    mediaUrl: "https://image.com",
    collectionId: "abc123"
  }) {
    id
    status
  }
}

Example response:

{
  "data": {
    "createTextTile": {
      "id": "tile999",
      "status": "ACTIVE"
    }
  }
}

Error handling

All errors are returned in the standard GraphQL errors array.

Example error response:

{
  "errors": [
    {
      "message": "Unauthorized",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

Common error codes:

• UNAUTHENTICATED → Missing or invalid token

• FORBIDDEN → User does not have permission for this resource

• NOT_FOUND → Requested entity does not exist

• INTERNAL_SERVER_ERROR → Unexpected server error

Business logic errors If error is a part of business logic, it will be returned in the problems array with code and message

Tools & testing

• Use GraphQL Playground (if enabled) for interactive exploration of the schema.

• Any GraphQL client library (Apollo, Relay, urql) can be used with Amondo's endpoints.