Skip to content
docs

API reference

The Maitento API is plain HTTP and JSON. The SDKs for TypeScript, Python and C# wrap it, and every call in this reference shows the plain request too, with curl, TypeScript and Python. It is generated from the code, so it always matches what the API does. To try a call without writing any code, use the API playground: it sends the call from your browser with your API key.

  • Calls by area: every call, grouped the way the SDKs group them.
  • Concepts: what each part of Maitento is for, and the definition file properties.
  • SDK source and READMEs: the TypeScript and Python SDKs are in sdks/, and the .NET SDK is Maitento.Sdk on NuGet.

Base URL and authentication

Section titled “Base URL and authentication”
https://api.maitento.com

Send your API key in the Authorization header: the word ApiKey, your user id and the secret, separated by spaces. The curl examples use $MAITENTO_AUTH:

export MAITENTO_AUTH="ApiKey ${MAITENTO_API_KEY/:/ }"

Your tenant always comes from the key, never from the URL. Something that belongs to another tenant answers 404.

Conventions

Section titled “Conventions”
  • JSON in and out, with camelCase names. Every field is present in a response; empty ones are null.
  • Ids are UUIDs. Dates are ISO 8601 in UTC. Durations are written "hh:mm:ss" ("00:05:00" is five minutes).
  • Names of definitions ({name}) are unique within a namespace ({namespaceName}).
  • Enums are strings such as "Finished". New values can appear, so don’t treat an unknown one as an error.
  • Lists of definitions come back whole. Lists of runs, builds and files are paged: pass the nextCursor from one page as cursor to get the next.

Errors

Section titled “Errors”
StatusBodyMeans
400{"validationFailures": [{"errorCode", "memberName", "message"}]}the request is invalid; branch on errorCode
401emptymissing, wrong or expired credentials
403empty, or {"code", "error"}you’re signed in but not allowed (for example, a member doing an admin’s job)
404emptynot found, or not yours
409{"error"}a concurrent change; read again and retry
413{"code": "api:request-too-large", ...}the body is too large
429{"code": "api:rate-limited", "retryAfterSeconds"}slow down; also sent as Retry-After

Branch on the status and the error code, never on the message text. Error codes lists every code, what it means and what to do.

Also in the reference

Section titled “Also in the reference”
  • Types: every object, enum and shape the API sends and receives, with its fields and an example. Every type named in this reference links to its page.
  • Error codes: every code the API answers with, by area, with its status and what to do.
  • Project files: every file in a Maitento project, every property it can set, and the VS Code extension that checks them as you type.
  • API playground: try any call from your browser.

Calls by area

Section titled “Calls by area”
maitento