Your project's own API documentation

Every project documents its own API for you. The documentation is generated from your data model, so an entity you created a minute ago is already in it, with its fields, types and example values. It also covers a selection of the platform's own endpoints. You can read it in the Anythink dashboard, send real requests from it, or fetch the underlying specification to use in other tools.

What you get#

The documentation comes in two parts.

Both parts are OpenAPI 3 documents, the standard format that tools such as Swagger UI, Postman and client generators read. The data model document covers the entity endpoints only. Endpoints such as bulk create, import, delete-many, record locking and the public record endpoints aren't in it. They're all described in REST API reference.

Open the docs in the dashboard#

anythink fetch /docs

Which endpoints does my project have for the orders entity?

Try a request from the dashboard#

The documentation page is interactive. Every operation has a Try it out button.

1. Expand an operation, for example GET /entities/orders/items.
2. Select Try it out, fill in any parameters or the request body, then select Execute.
3. The page shows the request it sent, the response status and body, and how long the call took.

The page signs each request with the session you're already signed in with, so you don't have to paste a token. The request runs as you: your role's permissions and any row-level security apply, exactly as they would in your own app. These are real calls. Create, update and delete change your data.

An API key doesn't work in the Try it out panel, because the page always sends your session. To test a key, send the request yourself:

curl https://api.my.anythink.cloud/org/{project_id}/entities/orders/items \
  -H "x-api-key: ak_your_key_here"

See API keys to create one, and Sign in users for tokens.

Get the specification#

The dashboard reads its documentation from one endpoint. You can call it too.

GET /org/{project_id}/docs
x-api-key: ak_your_key_here

You can authenticate with a user access token (Authorization: Bearer <access_token>) or an API key. The caller needs the anythink_documentation:read permission. A caller without it gets 403 Forbidden.

The response is a JSON object with two properties:

{
  "data_model_documentation": { "openapi": "3.0.3", "info": { "title": "Data Model API" }, "paths": { }, "components": { }, "tags": [ ] },
  "module_documentation": {
    "anythink": { "openapi": "3.0.4", "paths": { } }
  }
}

Each document lists your project's address as its server, with paths that already contain your project ID, so you can load one straight into a tool.

anythink fetch /docs

Fetch my project's API documentation and tell me which entities have a required email field.

Save a document as a file#

Use curl with an API key, then pull out the part you want with jq:

curl -s https://api.my.anythink.cloud/org/{project_id}/docs \
  -H "x-api-key: ak_your_key_here" > docs.json

jq '.data_model_documentation' docs.json > data-model.openapi.json
jq '.module_documentation.anythink' docs.json > anythink.openapi.json

Use the specification in other tools#

Because each document is OpenAPI 3, you can import it into an API client such as Postman or Insomnia, view it in Swagger UI or Redoc, or give it to an OpenAPI client generator to produce typed code for the five operations it describes.

Two things to know before you generate a client:

• The document declares a bearer token as its only security scheme, so a generated client signs in with an access token. If you use an API key, add the x-api-key header yourself.
• Paging, filters, fields and relationship expansion are described in REST API reference. Treat that page as the reference for list requests and for the endpoints the document leaves out.

Generate a new copy whenever your data model changes. The specification is built when you request it, so it's never out of date, but a client you generated earlier is.

What's included, and who can see it#

• Entities. The data model document lists the entities you created. Each entity's schema has all of its fields except id, created_at and updated_at, which Anythink sets for you.
• Field types. Each field is shown with the matching OpenAPI type. Relationship fields appear as the ID or IDs of the related records. A secret field is shown as a password-format string with a masked example.
• Examples. Example values are sample data for the field type, not your own records.
• Permissions. The documentation shows the shape of your API to anyone who can read it. It doesn't change what each caller may do. A user who can read the docs but lacks orders:read sees the orders operations and gets 403 Forbidden when they try one. Give anythink_documentation:read only to roles that should see your data model. See Roles and permissions.
• Data. The documentation never contains your records, only the shape of the API.
• Changes to the data model. The specification is generated on each request. Add an entity or a field, rename one or delete one, and the next request reflects it. In the dashboard, reload the page.

Limits#

Next steps#