# Basics

URL: https://submitator.com/docs/api/basics

> Check your key, read your account and download this reference.

Check your key, read your account and download this reference. Every request needs `Authorization: Bearer <key>`. The key's prefix decides the mode, and an id from one mode is never found in the other.

Ids are a type prefix (`prj_`, `lst_`, `dir_`, `evt_`, `rep_`, `img_`, `we_`, `wd_`, `key_`) and 22 letters and digits: treat them as opaque strings. Times are ISO 8601 in UTC. Lists return `object`, `data`, `has_more` and `next_cursor`; send `next_cursor` back as `cursor` to read the next page.

Send JSON with `Content-Type: application/json`; image uploads also accept `multipart/form-data`. A parameter the operation does not list returns 400 `unknown_parameter`, and an empty string counts as `null`.

Each account and mode can make 3,600 requests per UTC hour, or 600 before your first purchase. Every response carries `X-Request-Id`, and a request your key authenticates also gets `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` for your account and mode. Errors share one envelope: branch on `error.code`, show `error.message`, and quote `error.request_id` when you contact support.

## Check your key

`GET https://api.submitator.com/v1/ping`

Returns the agency and the key behind the request, and whether the key is live or test. Call it first when you set up an integration: a 200 means the key works, in the mode `livemode` shows.

Response 200:

```json
{
  "object": "ping",
  "ok": true,
  "livemode": false,
  "account": {
    "name": "Northlight Studio",
    "state": "active"
  },
  "key": {
    "id": "key_3Rw8Kx2Lq9Vt5Nb1Zm7HcW",
    "permissions": "full"
  }
}
```

Typical errors: [`api_key_missing`](https://submitator.com/docs/errors#api_key_missing), [`api_key_invalid`](https://submitator.com/docs/errors#api_key_invalid), [`rate_limited`](https://submitator.com/docs/errors#rate_limited).

## Read your account

`GET https://api.submitator.com/v1/account`

Shows how many launches you have left, how many listings are in progress across your projects, and your request budget for the current hour. Read it before a launch: with 0 launches available, a launch returns 402 `no_launches_left`.

Response 200:

```json
{
  "object": "account",
  "livemode": false,
  "name": "Northlight Studio",
  "state": "active",
  "launches": {
    "available": 97,
    "used": 3,
    "total": 100
  },
  "capacity": {
    "in_flight": 25,
    "limit": 100
  },
  "rate_limit": {
    "limit": 3600,
    "remaining": 3488,
    "resets_at": "2026-10-08T16:00:00Z"
  }
}
```

Typical errors: [`api_key_invalid`](https://submitator.com/docs/errors#api_key_invalid), [`rate_limited`](https://submitator.com/docs/errors#rate_limited).

## Download this reference

`GET https://api.submitator.com/v1/openapi.json`

Returns this reference as an OpenAPI 3.1 document in JSON, with the operations that are released. It needs no key, answers cross-origin GET requests and can be cached for 1 hour. Generate a client from it, or load it into your API tool.

Response 200:

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Submitator API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.submitator.com/v1"
    }
  ],
  "paths": {
    "/ping": {
      "get": {
        "operationId": "getPing",
        "summary": "Check your key"
      }
    }
  }
}
```

Typical errors: [`route_not_found`](https://submitator.com/docs/errors#route_not_found), [`internal_error`](https://submitator.com/docs/errors#internal_error).