Provisioning operation reference

Send requests to https://p-api.b2b-llm.com. The examples illustrate the wire contract; replace identifiers and secrets with values issued to your company. All Request/Response amounts remain decimal strings.

Authorization: Bearer mg_partner_...
Accept: application/json
Idempotency-Key: UNIQUE_LOGICAL_OPERATION

The Idempotency-Key header is required for mutations, not for read-only GET operations.

Transport and mutation discipline

Send owner authorization on every operation. Mutations also need a unique Idempotency-Key; repeat the original method/path/body with that key after an uncertain result. The replay window is seven days. Honor 429/Retry-After and preserve X-Request-ID. All responses are no-store JSON. Monetary strings stay exact and timestamps use UTC RFC3339. Unknown JSON/query fields are rejected. Collection limits are normally 1–100; follow each operation's opaque cursor field.

Provision an inference credential

Allocate the key inside an active company project. Capture the returned plaintext secret immediately into the application secret store; normal listing will not return it. The owner is the principal for Business keys provisioned through this API.

Request example

curl -X POST https://p-api.b2b-llm.com/api/v1/partner/keys \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: provision-key-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Service integration",
    "group_id": "GROUP_PUBLIC_ID",
    "rpm_limit": 30,
    "concurrency_limit": 2,
    "spend_limit": "20.0000000000",
    "usage_price_basis": "official_price",
    "usage_price_multiplier": "0.900000"
  }'

Response example

{
  "data": {
    "public_id": "KEY_PUBLIC_ID",
    "group_id": "GROUP_PUBLIC_ID",
    "name": "Service integration",
    "key_prefix": "mg_live_ab12",
    "key": "mg_live_ab12...",
    "status": "active",
    "rpm_limit": 30,
    "concurrency_limit": 2,
    "spend_limit": "20.0000000000",
    "usage": "0.0000000000",
    "total_spent": "0.0000000000",
    "usage_price_basis": "official_price",
    "usage_price_multiplier": "0.900000",
    "effective_usage_price_basis": "official_price",
    "effective_usage_price_multiplier": "0.900000"
  }
}

Page through credentials

The newest credentials appear first. Choose limit from 1 to 100 and follow meta.next_cursor as cursor while meta.has_more is true. A returned prefix is an identifier for display, not a usable secret.

Request example

curl https://p-api.b2b-llm.com/api/v1/partner/keys \
  -H "Authorization: Bearer mg_partner_..."

Response example

{
  "data": [
    {
      "public_id": "KEY_PUBLIC_ID",
      "group_id": "GROUP_PUBLIC_ID",
      "name": "Service integration",
      "status": "active",
      "spend_limit": "20.0000000000",
      "usage": "3.2500000000",
      "total_spent": "1.1400000000"
    }
  ]
}

Inspect a credential record

Address the key by its public ID. The response describes its current configuration and counters without granting access to another company's key.

Request example

curl https://p-api.b2b-llm.com/api/v1/partner/keys/KEY_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..."

Response example

{
  "data": {
    "public_id": "KEY_PUBLIC_ID",
    "group_id": "GROUP_PUBLIC_ID",
    "name": "Service integration",
    "status": "active",
    "rpm_limit": 30,
    "concurrency_limit": 2,
    "spend_limit": "20.0000000000",
    "usage": "3.2500000000",
    "total_spent": "1.1400000000",
    "effective_usage_price_basis": "official_price",
    "effective_usage_price_multiplier": "0.900000"
  }
}

Change credential settings

PATCH modifies only supported fields supplied by the caller. An empty group_id detaches the key; null valuation basis/multiplier restores inheritance. Check employee integration requirements before removing project context.

Request example

curl -X PATCH https://p-api.b2b-llm.com/api/v1/partner/keys/KEY_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: provision-key-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated user name",
    "group_id": "GROUP_PUBLIC_ID",
    "rpm_limit": 60,
    "concurrency_limit": 4,
    "spend_limit": "40.0000000000",
    "usage_price_basis": null,
    "usage_price_multiplier": null
  }'

Response example

{
  "data": {
    "public_id": "KEY_PUBLIC_ID",
    "spend_limit": "40.0000000000",
    "usage": "3.2500000000",
    "effective_usage_price_basis": "user_price",
    "effective_usage_price_multiplier": "1.000000"
  }
}

Revoke a credential

Use this operation only after identifying the affected application. Credential deletion/revocation does not erase the wallet ledger or historical settled charges.

Request example

curl -X DELETE https://p-api.b2b-llm.com/api/v1/partner/keys/KEY_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: provision-key-001" \

Response example

{"data":{"deleted":true}}

Suspend and resume admission

Freezing stops new inference without rotating the secret. Resumption requires the owner's verified email and otherwise valid account policy. A frozen credential's catalog access does not imply inference access.

Request example

curl -X POST https://p-api.b2b-llm.com/api/v1/partner/keys/KEY_PUBLIC_ID/freeze \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: provision-key-001" \

Response example

{"data":{"public_id":"KEY_PUBLIC_ID","status":"frozen"}}

Request example

curl -X POST https://p-api.b2b-llm.com/api/v1/partner/keys/KEY_PUBLIC_ID/unfreeze \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: provision-key-001" \

Response example

{"data":{"public_id":"KEY_PUBLIC_ID","status":"active"}}

Replace the bearer secret

Rotation produces a new secret for the same credential record. Update the consuming application securely and stop using the old value. The new full secret must be captured from this response.

Request example

curl -X POST https://p-api.b2b-llm.com/api/v1/partner/keys/KEY_PUBLIC_ID/rotate \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: provision-key-001" \

Response example

{
  "data": {
    "public_id": "KEY_PUBLIC_ID",
    "status": "active",
    "key_prefix": "mg_live_cd34",
    "key": "mg_live_cd34..."
  }
}

Open a new key budget window

This clears the resettable usage counter only. Lifetime spend and the company wallet are not reset or refunded.

Request example

curl -X POST https://p-api.b2b-llm.com/api/v1/partner/keys/KEY_PUBLIC_ID/reset-usage \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: provision-key-001" \

Response example

{
  "data": {
    "public_id": "KEY_PUBLIC_ID",
    "usage": "0.0000000000",
    "total_spent": "1.1400000000"
  }
}

Read the key counters

Read usage and lifetime spend as different decimal quantities. Valuation configuration can make the resettable counter differ from the actual money debited.

Request example

curl https://p-api.b2b-llm.com/api/v1/partner/keys/KEY_PUBLIC_ID/usage \
  -H "Authorization: Bearer mg_partner_..."

Response example

{
  "data": {
    "key_id": "KEY_PUBLIC_ID",
    "usage": "3.2500000000",
    "total_spent": "1.1400000000"
  }
}

Inspect remaining budget

A zero spend_limit means unlimited, with remaining represented as null. It is not a zero-dollar remaining allowance.

Request example

curl https://p-api.b2b-llm.com/api/v1/partner/keys/KEY_PUBLIC_ID/spent-limit \
  -H "Authorization: Bearer mg_partner_..."

Response example

{
  "data": {
    "key_id": "KEY_PUBLIC_ID",
    "spend_limit": "20.0000000000",
    "usage": "3.2500000000",
    "remaining": "16.7500000000"
  }
}

Read finalized request history

Use limit 1–100, default 10. Results are newest finished_at first; pass meta.next_cursor as before for the next older page. Detailed history normally retains seven days and reports the active window. Pricing snapshots preserve historical actual/reference rates and usage valuation; unavailable old snapshots are marked unavailable, not rebuilt from today's catalog. gateway_overhead_ms, upstream_first_token_ms and e2e_first_token_ms describe different timings; gateway E2E excludes client network/TLS time. Batch records include their saved protocol/job/custom_id/coefficient. Native sync/async records omit the batch object. Token-rate reconstruction uses saved rates, rounding the selected base to ten decimals before applying and rounding the multiplier. Stored cost/official_base_cost/usage_cost are authoritative. Raw request/response bodies are not included.

Request example

curl "https://p-api.b2b-llm.com/api/v1/partner/keys/KEY_PUBLIC_ID/requests?limit=10" \
  -H "Authorization: Bearer mg_partner_..."

Response example

{
  "data": [
    {
      "request_id": "01KZ...",
      "key_id": "KEY_PUBLIC_ID",
      "group_id": "GROUP_PUBLIC_ID",
      "model": "claude-opus-4.7",
      "endpoint": "messages",
      "method": "POST",
      "status": "succeeded",
      "status_code": 200,
      "is_stream": false,
      "request_mode": "batch",
      "batch": {
        "protocol": "claude",
        "job_id": "msgbatch_01K...",
        "custom_id": "request-1",
        "price_multiplier": "0.5"
      },
      "tokens": {
        "input": 120,
        "output": 45,
        "cached": 0,
        "cache_write": 0,
        "reasoning": 0,
        "total": 165
      },
      "cost": "0.0000345",
      "usage_cost": "0.00345",
      "official_base_cost": "0.000345",
      "currency": "USD",
      "usage_pricing": {
        "basis": "official_price",
        "base_field": "official_base_cost",
        "base_amount": "0.000345",
        "multiplier": "10",
        "usage_cost": "0.00345",
        "formula": "round(base_amount * multiplier, 10)"
      },
      "pricing_snapshot": {
        "available": true,
        "unit": "per_1m_tokens",
        "user_price": {
          "input": "0.2",
          "output": "1",
          "cache_read": "0.02",
          "cache_write": "0.25",
          "reasoning": "1"
        },
        "official_price": {
          "input": "1",
          "output": "5",
          "cache_read": "0.1",
          "cache_write": "1.25",
          "reasoning": "5"
        },
        "usage_price": {
          "input": "10",
          "output": "50",
          "cache_read": "1",
          "cache_write": "12.5",
          "reasoning": "50"
        }
      },
      "duration_ms": 842,
      "gateway_overhead_ms": 34,
      "upstream_first_token_ms": 156,
      "e2e_first_token_ms": 190,
      "settlement_status": "settled",
      "started_at": "2026-08-05T10:00:00Z",
      "finished_at": "2026-08-05T10:00:00.842Z"
    }
  ],
  "meta": {
    "key_id": "KEY_PUBLIC_ID",
    "limit": 10,
    "returned": 1,
    "order": "finished_at_desc",
    "next_cursor": "eyJ0IjoiMjAyNi0wOC0wNSAxMDowMDowMCIsInAiOiIwMUt...",
    "has_more": true
  }
}

Request example

curl "https://p-api.b2b-llm.com/api/v1/partner/keys/KEY_PUBLIC_ID/requests?limit=10&before=NEXT_CURSOR" \
  -H "Authorization: Bearer mg_partner_..."

Reconcile wallet movements

Wallet API usage is aggregated per billing owner and finish-time minute. Use transaction_id for durable reconciliation and request_count for the included request count. Aggregate debits intentionally have null balance_before, balance_after and api_key_id; per-key detail belongs to request history. Follow the opaque cursor rather than treating internal numeric IDs as public keys.

Request example

curl https://p-api.b2b-llm.com/api/v1/partner/transactions \
  -H "Authorization: Bearer mg_partner_..."

Response example

{
  "data": [
    {
      "transaction_id": "TRANSACTION_PUBLIC_ID",
      "type": "debit",
      "source": "api_usage_minute",
      "billing_minute_num": 29769120,
      "amount": "-0.0232000000",
      "request_count": 100,
      "balance_before": null,
      "balance_after": null,
      "api_key_id": null,
      "created_at": "2026-08-05T10:00:00Z"
    }
  ]
}

Read the owner wallet

Use the Partner credential for an owner-level wallet check, including reconciliation after a balance alert. Do not substitute project usage for balance.

Request example

curl https://p-api.b2b-llm.com/api/v1/partner/balance \
  -H "Authorization: Bearer mg_partner_..."

Response example

{"data":{"balance":"1234.5678900000","currency":"USD","as_of":"2026-08-28T07:00:00Z"}}

Review provisioning activity

Audit entries identify successful management operations, action/target, request ID, source IP, safe metadata and UTC time. Secrets, replay bodies and idempotency keys are excluded. Filter by action where needed and use cursor to continue.

Request example

curl "https://p-api.b2b-llm.com/api/v1/partner/audit-events?limit=100" \
  -H "Authorization: Bearer mg_partner_..."

Create a project budget

A group collects credentials under one company, with shared request ceilings and usage valuation. Creating it does not allocate a separate wallet.

Request example

curl -X POST https://p-api.b2b-llm.com/api/v1/partner/groups \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: provision-key-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Telegram bot A",
    "description": "Keys created by bot A",
    "rpm_limit": 100,
    "concurrency_limit": 20,
    "spend_limit": "1000.0000000000",
    "usage_price_basis": "official_price",
    "usage_price_multiplier": "0.900000"
  }'

Response example

{
  "data": {
    "public_id": "GROUP_PUBLIC_ID",
    "name": "Telegram bot A",
    "status": "active",
    "spend_limit": "1000.0000000000",
    "usage": "0.0000000000",
    "total_spent": "0.0000000000",
    "usage_price_basis": "official_price",
    "usage_price_multiplier": "0.900000"
  }
}

Enumerate company projects

List project records within the owner scope and follow pagination. Public group IDs are stable references for subsequent key operations.

Request example

curl https://p-api.b2b-llm.com/api/v1/partner/groups \
  -H "Authorization: Bearer mg_partner_..."

Response example

{"data":[{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A","status":"active","usage":"0.0000000000"}]}

Inspect and edit a project

Read the group before changing its limits. PATCH applies supported fields; key overrides can still take precedence over inherited project settings.

Request example

curl https://p-api.b2b-llm.com/api/v1/partner/groups/GROUP_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..."

Response example

{"data":{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A","spend_limit":"1000.0000000000","usage":"12.0000000000"}}

Request example

curl -X PATCH https://p-api.b2b-llm.com/api/v1/partner/groups/GROUP_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: provision-key-001" \
  -H "Content-Type: application/json" \
  -d '{"name":"Telegram bot A production","status":"active","spend_limit":"2000.0000000000","usage_price_basis":"user_price","usage_price_multiplier":"1.200000"}'

Response example

{"data":{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A production","spend_limit":"2000.0000000000","usage_price_basis":"user_price","usage_price_multiplier":"1.200000"}}

Remove an empty project

Move or remove every member key first. A nonempty project returns 409 group_not_empty; do not rely on deletion to silently detach active integrations.

Request example

curl -X DELETE https://p-api.b2b-llm.com/api/v1/partner/groups/GROUP_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: provision-key-001" \

Response example

{"data":{"deleted":true}}

Reset the shared budget counter

The operation clears group usage without clearing each key's counter or altering settled wallet transactions. Confirm the intended budget scope before resetting.

Request example

curl -X POST https://p-api.b2b-llm.com/api/v1/partner/groups/GROUP_PUBLIC_ID/reset-usage \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: provision-key-001" \

Response example

{"data":{"public_id":"GROUP_PUBLIC_ID","usage":"0.0000000000","total_spent":"8.5000000000"}}

List a project's keys

Here members means API-key membership in the group. Employee organization/group permissions are managed separately in the account workspace.

Request example

curl https://p-api.b2b-llm.com/api/v1/partner/groups/GROUP_PUBLIC_ID/members \
  -H "Authorization: Bearer mg_partner_..."

Response example

{"data":[{"public_id":"KEY_PUBLIC_ID","name":"Service integration","status":"active","usage":"3.2500000000","total_spent":"1.1400000000"}]}

Assign a key to a project

Both public IDs must belong to the owner scope. The returned membership reflects the updated project. Reassess inherited limits and routing after a move.

Request example

curl -X POST https://p-api.b2b-llm.com/api/v1/partner/groups/GROUP_PUBLIC_ID/members \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: provision-key-001" \
  -H "Content-Type: application/json" \
  -d '{"key_id":"KEY_PUBLIC_ID"}'

Response example

{"data":[{"public_id":"KEY_PUBLIC_ID","name":"Service integration","status":"active"}]}

Detach a project key

Remove group membership deliberately; an employee integration may require an active project for execution. The operation does not delete historical request records.

Request example

curl -X DELETE https://p-api.b2b-llm.com/api/v1/partner/groups/GROUP_PUBLIC_ID/members/KEY_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: provision-key-001" \

Response example

{"data":{"removed":true}}

Read project budget use

These counters describe the shared resettable usage limit. They are not an independent prepaid balance.

Request example

curl https://p-api.b2b-llm.com/api/v1/partner/groups/GROUP_PUBLIC_ID/usage \
  -H "Authorization: Bearer mg_partner_..."

Response example

{"data":{"group_id":"GROUP_PUBLIC_ID","usage":"12.0000000000","total_spent":"8.5000000000","usage_reset_at":"2026-08-01T00:00:00Z"}}

Query completed project activity

Supply from/to as UTC RFC3339 values ending in Z; up to six fractional digits are accepted. Statistics come from completed-request minute aggregates keyed by finish time. The open minute is excluded. average_duration_ms is full gateway request duration, not first-token time or gateway overhead.

Request example

curl "https://p-api.b2b-llm.com/api/v1/partner/groups/GROUP_PUBLIC_ID/stats?from=2026-08-01T00:00:00Z&to=2026-08-05T23:59:59Z" \
  -H "Authorization: Bearer mg_partner_..."

Response example

{
  "data": {
    "group_id": "GROUP_PUBLIC_ID",
    "requests": 120,
    "errors": 3,
    "input_tokens": 50000,
    "output_tokens": 12000,
    "cached_tokens": 8000,
    "cache_write_tokens": 1200,
    "reasoning_tokens": 2000,
    "cost": "8.5000000000",
    "average_duration_ms": "842.50",
    "from": "2026-08-01T00:00:00Z",
    "to": "2026-08-05T23:59:59Z"
  }
}

Retrieve retained inference output

The request must belong to this account and remain within its result-retention interval. A pending result has no completed body; a terminal result carries the saved response status/body or error. Unknown, expired and foreign IDs are not returned.

Request example

curl https://p-api.b2b-llm.com/api/v1/requests/01KZ... \
  -H "Authorization: Bearer mg_partner_..."

Response example

{
  "data": {
    "request_id": "01KZ...",
    "status": "processing",
    "created_at": "2026-08-05T10:00:00Z",
    "started_at": "2026-08-05T10:00:00Z",
    "completed_at": null,
    "expires_at": "2026-08-06T10:00:00Z"
  }
}

Response example

{
  "data": {
    "request_id": "01KZ...",
    "status": "completed",
    "response_status": 200,
    "response_headers": {"Content-Type":"application/json"},
    "response": {"id":"resp_example","status":"completed"},
    "completed_at": "2026-08-05T10:00:05Z",
    "expires_at": "2026-08-06T10:00:00Z"
  }
}

Operational error responses

Use the error type/code together with HTTP status. Mutation bodies are limited to 1 MiB. A reused idempotency key with different input produces 409. Rate limiting returns partner_rate_limit_exceeded with Retry-After. Unsupported methods include Allow and remain JSON, not HTML.

Response example

{"error":{"type":"invalid_token","message":"Invalid Partner API key"}}

Response example

{"error":{"type":"not_found","message":"API key not found"}}

Response example

{"error":{"type":"invalid_request","message":"limit must be an integer from 1 to 100"}}

Company identity rules

Only the verified company owner can use a Business Partner token. Employee-principal assignment is deliberately a workspace operation. A supplied group_id must identify an active project owned by the company; an invalid value is rejected rather than downgraded to an ungrouped key. History may include the executing principal's public identifier separately from the billing owner.

Exact Partner route inventory

This table is the PartnerBearer contract on the Partner API host; it is not an Images polling surface. Public webhook signatures and portal sessions are separate. The PHP Router suppresses GET response bodies for HEAD; only canonical API methods are listed below.