OpenAPI Overview

The public API is built for scripts, CLIs and dashboards. It authenticates with a personal Access Token (mgpat_) and acts as the account owner.

Base URL: https://modelgo-web-api.modelgo.ai/api/openapi/v1
Machine-readable spec: OpenAPI JSON / YAML

Authentication

Create a token under Console → Personal settings → Security & sign-in → Access Token (one active token per account). The plaintext is shown once.

http

Authorization: Bearer mgpat_xxxxxxxx

Only a Bearer token is accepted; console session cookies / CSRF are not.
The token belongs to the account, not a tenant. It can read every tenant the account is an active member of.
Changing the password, resetting it or disabling the account revokes the token immediately.

Choosing a tenant

Use X-Tenant-Id. When omitted, the account's default tenant is implied, with one exception below.

A tenant the caller is not a member of returns 403 forbidden / access_denied.
Balance, usage and cost: omitting X-Tenant-Id returns a list of every readable tenant, {"items":[...]}. Passing it returns a single object. Unreadable tenants never appear; a tenant whose upstream read fails is reported as error=unavailable (balance: balance_status=unavailable).

Errors

Every failure uses its real HTTP status and this body:

json

{
  "error": {
    "code": "invalid_request",
    "error_class": "invalid_request",
    "reason": "status",
    "message": "human readable",
    "request_id": "...",
    "trace_id": "..."
  }
}

Branch on code + reason; message is for humans only.

HTTP	code	Meaning
400	`invalid_request`	Missing/invalid parameter; `reason` names the field
401	`invalid_token`	Missing, malformed, unknown, revoked or expired token
401	`unauthorized`	Call not found or not visible (indistinguishable)
403	`forbidden`	Not a tenant member / role not allowed
404	`not_found`	Resource or path does not exist
409	`conflict` / `idempotency_conflict`	State conflict / idempotency key reuse
429	`rate_limited`	Throttled; retry after `Retry-After`
500/503	`internal_error` / `idempotency_unavailable`	Server error / idempotency store unavailable

Rate limits

Surface	Per-token limit
Balance	60 / minute
Usage, cost, call detail	30–60 / minute
Management writes / export writes	10 / minute

Exceeding a limit returns 429 with Retry-After and X-RateLimit-Limit/Remaining/Reset.

Conventions

Amounts are decimal strings in the settlement currency (CNY / USD); no FX conversion.
Timestamps are UTC RFC3339.
Lists and exports use opaque cursors (cursor, has_more, next_cursor).
Writes (create/update/delete key, create export) require Idempotency-Key; the same key with the same request replays the stored response, a different request returns 409 idempotency_conflict.