Partner API

The Partner API is intended for banks, bots, reseller panels, internal provisioning systems, and other trusted server-to-server integrations. Version 10.5.0 is the first Bank-ready machine contract.

Base URL

https://p-api.model-gate.com

Authentication

Authorization: Bearer mg_partner_...

Every response is JSON, including 404, 405, 429, and 500, and includes X-Request-ID. Responses use Cache-Control: no-store; the Partner host does not use browser PHP sessions. All external timestamps are UTC RFC3339 (YYYY-MM-DDTHH:MM:SSZ).

All POST, PATCH, and DELETE operations require a unique Idempotency-Key header. Model Gate keeps the encrypted result for 7 days so a retry of the same request returns the original result without performing the mutation again. Reusing the same key for a different method/path/body returns HTTP 409.

Partner requests are protected by an account-level per-minute rate limit configured by PARTNER_API_RATE_LIMIT_PER_MINUTE (default 600). Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; HTTP 429 also includes Retry-After.

Create or regenerate the Partner API key in the Model Gate profile. The complete bearer token is shown only once at generation/rotation and Model Gate stores only its SHA-256 hash plus a display prefix. Save the token immediately in your server-side secret manager; if it is lost, rotate it.

The profile has a separate API IP allowlist. When it is non-empty, Partner API requests must originate from an allowed exact IPv4/IPv6 address or CIDR prefix. Business organization API rules apply in addition to the personal rule. A source rejected by either effective allowlist receives HTTP 403 with error.type = ip_not_allowed.

For Business accounts, the Partner API credential is available only to the verified organization owner. Employee principals and delegated Business credential assignment are managed in the web panel, where group execution permissions can be validated. Partner-created Business keys therefore use the owner as both billing owner and credential principal. A supplied group_id must name an active group owned by the account; an unknown/frozen group is rejected with HTTP 422 instead of silently creating an ungrouped key.

Decimal values

Financial and usage fields are always JSON strings:

{
  "spend_limit": "100.0000000000",
  "usage": "12.3456789000",
  "remaining": "87.6543211000",
  "usage_price_multiplier": "0.900000"
}

Use arbitrary-precision decimal arithmetic. Never convert these values to float.

Capabilities

• Create, list, update, rotate, freeze, unfreeze, and delete API keys.
• Configure per-key usage valuation.
• Create and manage groups.
• Move keys between groups.
• Read key and group usage.
• Read finalized request history for a key in finish-time order with 1–100 row pages and token/price breakdown. Detailed request history is hot-retained for API_REQUESTS_HOT_RETENTION_DAYS (default 7 days); longer-term financial reconciliation uses the balance transaction journal.
• Read current account balance and account balance transactions with cursor pagination.
• Read Partner management audit events with cursor pagination.
• Poll asynchronous inference results.

See all Partner API endpoints for complete request and response examples.

Recent request-history records include principal_user_id when the credential principal still exists, separately from the company billing owner.

Machine-readable contract

The OpenAPI 3.1 contract is shipped with each release as resources/contracts/partner-api.openapi.yaml. Treat it together with these Partner API pages as the Bank integration contract. Unknown JSON fields and unknown query parameters are rejected rather than silently ignored.