Projects, Budgets, and API Keys

Manage Team projects, budgets and API keys, and query project and key usage with a Management API Key

Use a Management API Key to manage your Team's projects, spending limits and model API keys, and query project and key usage.

Management key required

All endpoints on this page use a mgmt-... management key belonging to your Team. As Team Owner, create one in Console under Developer → Management API Keys. See Management API Keys for the steps.

Base URL: https://api.atlascloud.ai/public/v1

Requests use the Team account associated with the management key. Its permissions cover all projects and members' model API keys in that Team.

Resource limits

ResourceCurrent limit
Projects20 active projects per Team, including the default project. Archived projects do not count. At the limit, creation returns 409 with project_limit_exceeded.
API key countNo fixed per-account or per-project count cap is currently enforced. Authorization, name uniqueness and request rate limits still apply. This is not a guarantee of unlimited creation throughput.
Project name2–64 Unicode characters after trimming; unique within the account. Archived projects retain their names.
API key name1–128 Unicode characters after trimming; unique among non-deleted keys across the account, including other projects. Case changes do not make a name unique.
JSON bodyMaximum 64 KiB; unsupported fields are rejected.

The billing query parameter api_key_ids[] accepts up to 100 IDs per query. That is a filter limit, not an API key creation limit. Public API rate limits return 429; respect Retry-After when present.

1. Create a project with an initial budget

curl -X POST "https://api.atlascloud.ai/public/v1/projects" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-123",
    "description": "Customer 123",
    "budget": {
      "monthly_limit": {"value": "100.00", "currency": "usd"},
      "usage_alert_percent": 80
    }
  }'

Save the returned id (a project UUID) as PROJECT_ID in your backend. Project creation, its initial budget, and the creator's project-admin membership are atomic. Omitting budget, passing null, or passing {} creates an unlimited budget. The optional description allows up to 50 Unicode characters after trimming.

2. Replace the project's budget

curl -X PUT "https://api.atlascloud.ai/public/v1/projects/$PROJECT_ID/budget" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_limit": {"value": "20.00", "currency": "usd"},
    "monthly_limit": {"value": "200.00", "currency": "usd"},
    "usage_alert_percent": 80
  }'

PUT replaces the entire budget

Resend every setting you want to keep. Omitted or null monetary fields become zero: zero means unlimited for a limit, or disabled for an alert. Omitted usage_alert_percent becomes zero. Sending {} removes all project budget limits and alerts.

FieldMeaning
daily_limitSpending limit for the current UTC calendar day
weekly_limitSpending limit for the UTC week beginning Monday at 00:00
monthly_limitSpending limit for the current UTC calendar month
total_limitCumulative project spending limit
daily_alert, monthly_alertSpending reminder thresholds
usage_alert_percentMonthly-budget reminder percentage, 0–100; a positive value requires a positive monthly_limit

Amounts are USD decimal strings with up to 8 integer digits and 8 fractional digits. Budget responses preserve 8 fractional digits; billing report responses use 6. These limits apply to Atlas usage costs, not to credits or prices you sell to your own customers.

Updating a budget preserves existing usage. Sending the same PUT repeatedly does not reset spending. Raising a limit above current usage can permit subsequent requests once the existing budget checks refresh, provided all other account, project, member and key conditions allow them. Budget enforcement is not a prepaid reservation: concurrent or in-flight requests and delayed settlement can cause overspend. Archived projects cannot be modified.

3. Create a project-bound key

curl -X POST "https://api.atlascloud.ai/public/v1/api-keys" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"customer-123-primary\",\"project_id\":\"$PROJECT_ID\"}"

Optionally send expires_at as a future RFC 3339 timestamp. Omitting it or passing null means no expiration. The response returns:

  • id: the stable ak_... identifier, which cannot authenticate requests.
  • key: the secret apikey-... credential, returned only once on successful creation.
  • project_id, name, redacted, enabled, created_at, expires_at, and request_id.

The response has Cache-Control: no-store. The returned apikey-... key is a model API key, not a management key. Existing account, project and member spending rules apply; this endpoint does not set an additional key-level allowance.

The id in the creation response is the {api_key_id} in subsequent endpoint URLs. For example, a successful creation returns:

{
  "object": "api_key",
  "id": "ak_0123456789ABCDEFGHIJKL",
  "name": "customer-123-primary",
  "project_id": "019a6eab-7c00-7000-8000-000000000123",
  "key": "apikey-REPLACE_WITH_SECRET_RETURNED_ONCE",
  "redacted": "apikey-xxxx********xxxx",
  "enabled": true,
  "created_at": "2026-11-01T00:00:00Z",
  "expires_at": null,
  "request_id": "req_example"
}
ValueWhere to use it
Response id: ak_0123456789ABCDEFGHIJKLThe {api_key_id} in subsequent URLs, or API_KEY_ID in the examples
Response key: apikey-...The Authorization: Bearer header for model calls
Management key from Console: mgmt-...The Authorization: Bearer header for project and key management calls

For example, put the returned id into the URL to query this key's usage:

API_KEY_ID="ak_0123456789ABCDEFGHIJKL"
curl --get "https://api.atlascloud.ai/public/v1/api-keys/$API_KEY_ID/usage" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  --data-urlencode "from=2026-11-01T00:00:00Z" \
  --data-urlencode "to=2026-11-02T00:00:00Z"

Use the same API_KEY_ID to disable or delete the key and set its allowance. Save the response id alongside the project and key name; the Public API currently has no key list endpoint.

4. List and retrieve projects

curl --get "https://api.atlascloud.ai/public/v1/projects" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  --data-urlencode "status=active" \
  --data-urlencode "limit=20"

curl "https://api.atlascloud.ai/public/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY"

The list endpoint defaults to status=active; use status=archived for archived projects. limit defaults to 100 and accepts 1–100. The response includes data, has_more, next_page and request_id. Results are ordered by project UUID ascending. When has_more=true, send next_page as the next request's after query parameter with the same status. The last page has next_page=null; an empty list has data=[]. Pagination does not provide a snapshot during concurrent changes.

Each project includes its current budget. The detail endpoint also returns archived projects. Unknown projects and projects from another Team return 404.

5. Replace a key's allowance

curl -X PUT "https://api.atlascloud.ai/public/v1/api-keys/$API_KEY_ID/allowance" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "periodic",
    "period": "monthly",
    "amount": {"value": "100.00", "currency": "usd"}
  }'

The allowance endpoint replaces the whole key-level allowance. type is required:

TypeMeaningRequired settings
unlimitedNo key-level spending limitOmit period; omit amount, pass null, or use zero
fixedCumulative limit from key creationPositive amount; omit period
periodicLimit for a UTC calendar periodPositive amount; period is daily, weekly or monthly

Weeks begin Monday at 00:00 UTC. Amounts use the same USD format and 8-digit precision as project budgets. The response includes object=api_key_allowance, api_key_id, type, amount, request_id, and period for a periodic allowance.

Updating an allowance preserves the secret, enabled state, creation time and existing usage. A limit below current usage is allowed; enforcement follows the existing gateway cache refresh and settlement behavior. Disabled, expired and archived-project keys can have their allowance updated. Deleted keys return 404.

6. Query project and key usage

curl --get "https://api.atlascloud.ai/public/v1/projects/$PROJECT_ID/usage" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  --data-urlencode "from=2026-11-01T00:00:00Z" \
  --data-urlencode "to=2026-11-02T00:00:00Z"

curl --get "https://api.atlascloud.ai/public/v1/api-keys/$API_KEY_ID/usage" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  --data-urlencode "from=2026-11-01T00:00:00Z" \
  --data-urlencode "to=2026-11-02T00:00:00Z"

Both from (inclusive) and to (exclusive) are required RFC 3339 timestamps after the Unix epoch. The window must be non-empty, span at most 31 days, and have both ends aligned to UTC hour boundaries. Unknown or repeated query parameters return 400.

Example key usage response:

{
  "object": "api_key_usage",
  "api_key_id": "ak_0123456789ABCDEFGHIJKL",
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-11-02T00:00:00Z",
  "requests": 12,
  "successes": 10,
  "failures": 2,
  "amount": {"value": "1.230000", "currency": "usd"},
  "request_id": "req_example"
}

Project usage returns object=project_usage and project_id instead of api_key_id. It includes every member and request source in the project; key usage includes only that key's API-key-based sources. Archived projects and disabled, expired or deleted keys retain their historical usage. An empty window returns zero counters and zero amount.

These endpoints use the same analytics rollups as Console. requests equals successes + failures and counts completed or failed metered requests, excluding in-flight and Coding Plan requests. amount is settled charged USD, including failed requests that were charged, formatted to 6 decimal places. Aggregation and settlement can lag, so recent results may change. These are not real-time allowance counters and do not return token counts, image counts or video seconds. For daily model quantities and costs, use the separate Billing Public API with a model API key.

7. Archive a project

curl -X POST "https://api.atlascloud.ai/public/v1/projects/$PROJECT_ID/archive" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY"

Archival is permanent and needs no request body. It removes project memberships and invalidates pending join requests together. A member who loses their last project also loses Team membership. Historical usage remains available. Project keys become unusable without changing their explicit enabled state; the project rejects new keys and budget updates.

The default project cannot be archived (400). Repeating the request for an archived project returns 200 and the archived project. There is no restore endpoint.

8. Disable or delete a key

curl -X POST "https://api.atlascloud.ai/public/v1/api-keys/$API_KEY_ID/disable" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY"

curl -X DELETE "https://api.atlascloud.ai/public/v1/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY"

Both calls need no request body and can operate on any member's model key in this Team, including keys in archived projects. Disable returns 200 with object=api_key, id, enabled=false and request_id; repeated disabling succeeds. Delete returns 204 with no response body, including when the same Team's key has already been deleted.

Deletion is permanent and preserves usage history. Deleted keys cannot be disabled again or have their allowance changed. Unknown or other-Team keys return 404. Revocation follows existing gateway cache refresh behavior.

Errors and retries

Creation POST requests do not support idempotent replay. Duplicate names return 409 / already_exists; retrying with the same name cannot recover a secret key. If a creation response is lost, inspect the resource in Console before retrying; delete an unusable key and create a replacement when necessary. Archival, disabling and deletion can be repeated as described above; repeating a budget or allowance replacement does not reset usage.

Other errors use the Public API error envelope: 400 for invalid input, 401 for invalid credentials, 403 for insufficient permission or an inactive project/account, 404 for a project or key absent from the authenticated account, 413 for an oversized body, 415 for an unsupported content type, and 429 for rate limits. Save request_id for troubleshooting without saving secrets.

Last updated on

On this page