Management API

The management API reads and changes your Mubit organization from code: its keys, calls, tasks, adapter versions, lessons, imports, usage and billing. Use it for scripts, CI jobs and internal tools. Model calls don't use it: they go to the paths in the API reference.

This reference lists only the operations the API serves today.

Base URL

https://api.mubit.ai/api/v1

Call it from your server, not from a browser.

OpenAPI file

The whole reference is one OpenAPI 3.1 file: openapi.json. Generate a client from it, or load it in an API tool. The pages below are made from the same file.

Management keys

Each request carries a management key in the Authorization header:

Authorization: Bearer YOUR_MANAGEMENT_KEY

Management keys start with mwm_. An admin of your organization creates them in the console, under Workspace, Management keys, or with Create management key. The key's secret is shown once, when it is created or rotated. Store it then.

A Mubit key for model calls (mbt_ or mw_) is not a management key, and the management API refuses it. A management key is refused on the model-call paths.

The SDKs read the management key from MUBIT_MANAGEMENT_KEY.

Roles

Each management key has a role. Each operation names the lowest role it needs.

A key can't create or rotate a key of a higher role than its own (403 role_ceiling).

Project-bound keys

A key created with a project reaches only that project. Its lists hold only that project's records, and a record of another project is 404. The organization-wide operations are 403 project_scoped for it: the organization, its inference keys, provider keys and management keys, and Get billing status.

Retries

Every POST takes an Idempotency-Key header of 1 to 255 characters. Send a new value for each change, and the same value when you retry it:

• A retry with the same key, route and body within 24 hours gets the first answer again, with Idempotent-Replayed: true. Nothing runs twice.
• The same key with another body is 409 idempotency_conflict.
• A retry while the first request still runs is 409 with Retry-After: 1.

The answer that holds a new key's secret is never replayed.

The SDKs add an Idempotency-Key to each POST for you.

Pagination

Lists take limit (1 to 200, default 50) and cursor. An answer has data and next_cursor. To read the next page, send next_cursor as cursor, with the same filters. next_cursor is null on the last page.

A cursor lasts 24 hours and belongs to its organization, project scope and filters. Any other use is 400 invalid_cursor.

The SDKs' list calls page for you:

import { Mubit } from "@mubit-ai/sdk";
 
const client = new Mubit({ managementKey: process.env.MUBIT_MANAGEMENT_KEY });
 
for await (const task of client.tasks.list()) {
  console.log(task.id, task.stage);
}

Rate limits

A key can send 600 requests a minute. List task training examples also has a limit of 120 requests a minute for the whole organization.

Every answer has RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. Past a limit, the answer is 429 rate_limited with Retry-After in seconds.

Errors

An error answer has this shape:

{
  "error": {
    "code": "role_required",
    "message": "Operation requires role 'admin'",
    "request_id": "req_403abc"
  }
}

Branch on code, not on message. Every answer has an x-request-id header; give it to support when you ask about a request.

Operations