# API Reference

## 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](https://graphql.org/) 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://pub.amondo.com
```

Use `pub.amondo.com` for requests that fetch published content (e.g. `imprintPublication`). It is public, read-only, cached, and requires no authentication.

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:

```bash
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` — available on `pub.amondo.com` (no auth)
* `mutation login`
* `mutation submitQuizResults`
* `mutation votePoll`
* `query pollTileResults`

## 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](mailto:support@amondo.com).

## Getting a token

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

**Example request:**

```graphql
mutation {
  login(email: "user@example.com", password: "secret") {
    token
    user {
      id
      email
    }
  }
}
```

**Example response:**

```json
{
  "data": {
    "login": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "user": {
        "id": "12345",
        "email": "user@example.com"
      }
    }
  }
}
```

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. This query runs against `pub.amondo.com` — the public, read-only, cached endpoint. No authentication is required.

**Parameters:**

* `id: UUID!` — the publication ID

**Key fields on `ImprintPublication`:**

| Field         | Type            | Description                    |
| ------------- | --------------- | ------------------------------ |
| `id`          | `UUID!`         | Publication ID                 |
| `publishedAt` | `DateTime!`     | When the imprint was published |
| `imprint`     | `IBaseImprint!` | The imprint data (see below)   |

**Key fields on `imprint` (`IBaseImprint`):**

| Field                       | Type           | Description                                     |
| --------------------------- | -------------- | ----------------------------------------------- |
| `id`                        | `UUID!`        | Imprint ID                                      |
| `slug`                      | `String!`      | URL slug                                        |
| `title`                     | `String!`      | Imprint title                                   |
| `mode`                      | `ImprintMode!` | `CAROUSEL`, `GALLERY`, or `STORIES`             |
| `analyticsTag`              | `String`       | Analytics identifier                            |
| `createdAt`                 | `DateTime!`    | Creation timestamp                              |
| `team`                      | `PublicTeam!`  | Team (`id`, `name`)                             |
| `layoutV2(device: Device!)` | `Layout`       | Layout sections/tiles for `DESKTOP` or `MOBILE` |

**Example request:**

```graphql
query {
  imprintPublication(id: "e4f7a1b2-3c4d-5e6f-7a8b-9c0d1e2f3a4b") {
    id
    publishedAt
    imprint {
      id
      slug
      title
      mode
      analyticsTag
      createdAt
      team {
        id
        name
      }
      layoutV2(device: DESKTOP) {
        sections {
          tiles {
            id
          }
        }
      }
    }
  }
}
```

**Example response:**

```json
{
  "data": {
    "imprintPublication": {
      "id": "e4f7a1b2-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
      "publishedAt": "2025-11-01T12:00:00Z",
      "imprint": {
        "id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "slug": "my-imprint",
        "title": "My Imprint",
        "mode": "CAROUSEL",
        "analyticsTag": "campaign-2025",
        "createdAt": "2025-10-15T09:30:00Z",
        "team": {
          "id": "t1e2a3m4-5678-9abc-def0-123456789abc",
          "name": "My Team"
        },
        "layoutV2": {
          "sections": [
            {
              "tiles": [
                { "id": "tile-001" },
                { "id": "tile-002" }
              ]
            }
          ]
        }
      }
    }
  }
}
```

> For the full schema, use introspection on `https://gql.amondo.com`. The cached endpoint (`pub.amondo.com`) does not expose a sandbox or playground.

### 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:**

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

**Example response:**

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

## Error handling

All errors are returned in the standard GraphQL errors array.

**Example error response:**

```json
{
  "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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amondo.com/developer-guides/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.