Introduction
The Admin API lets you manage regular organization API keys, inspect organization billing data, and access container-related APIs with an admin API key. Admin API keys are for organizations, not personal accounts.Common use cases
- Automating key management: Create, rotate, or delete API keys programmatically, and set expiration dates or token limits based on your business logic.
- Building custom dashboards: Display usage metrics, cost breakdowns by model, and historical trends using the billing and time-series endpoints.
- Monitoring usage: Query aggregated or per-key usage statistics to track costs and token consumption.
- Managing containers programmatically: Create, validate, update, stop, start, and delete containers. Manage org secrets, SSH keys, custom domains, registry credentials, and container grouping from automation.
Authentication
Admin API keys provide programmatic access to your account resources. Admin keys are prefixed withadmin_ and must be included in the Authorization header as a Bearer token.
Need to create an admin API key? Follow our step-by-step guide: Getting a Tinfoil Admin Key
Available endpoints
This page covers the following endpoints:API key management
GET /api/keys- List API keysPOST /api/keys- Create a new API keyPOST /api/keys/update- Update an API key name or token capDELETE /api/keys/:key- Delete an API key
Billing & usage
GET /api/billing/usage- Get aggregated usage statistics for all keysPOST /api/billing/usage/key- Get usage statistics for a specific keyGET /api/billing/time-series- Get time series dataGET /api/billing/transactions- Get transaction history
Container endpoints
- Lifecycle & deployment
POST /api/containers/validate-name- Validate a container name or custom domain before deployPOST /api/containers/validate- Validatetinfoil-config.ymlbefore deployGET /api/containers/hosts- List hosts available to the organizationGET /api/containers- List containersGET /api/containers/:id- Get a specific containerPOST /api/containers- Create a containerPOST /api/containers/:id/relaunch- Relaunch a running or failed containerPOST /api/containers/:id/stop- Stop a running containerPOST /api/containers/:id/start- Start a stopped containerDELETE /api/containers/:id- Delete a containerGET /api/containers/:id/update- Get in-progress update statusPOST /api/containers/:id/update/cancel- Cancel an in-progress updatePOST /api/containers/:id/auto-update- Toggle auto-updatePOST /api/containers/:id/github-connection- Toggle GitHub App connectionGET /api/containers/:id/metrics- Get resource metrics
- Organization
PUT /api/containers/:id/group- Move a container into or out of a groupPUT /api/containers/reorder- Reorder containersPUT /api/containers/groups/rename- Rename a groupPUT /api/containers/groups/reorder- Reorder groupsDELETE /api/containers/groups/:name- Delete a group
- Related resources
GET /api/secrets- List org secretsPOST /api/secrets- Create a secretGET /api/secrets/:name- Get a secret’s metadataPUT /api/secrets/:name- Update a secretDELETE /api/secrets/:name- Delete a secretGET /api/ssh-keys- List org SSH keysPOST /api/ssh-keys- Create an SSH keyDELETE /api/ssh-keys/:name- Delete an SSH keyGET /api/domains- List custom domainsPOST /api/domains- Add a domainPOST /api/domains/:domain/verify- Verify a domainDELETE /api/domains/:domain- Delete a domainGET /api/registry-credentials- List private registry credential statusPUT /api/registry-credentials/:registry- Create or update private registry credentialsDELETE /api/registry-credentials/:registry- Delete private registry credentials
API Key Management
List API Keys
Returns all regular (non-admin) API keys in your organization. Keys you created are returned in full. Keys created by other members are masked (for example,
tk_12345***).Example Request
Response
Create API Key
Creates a new regular API key for your organization. Requires active token billing for the organization.
Request Body
Name for the API key. Must contain only alphanumeric characters, hyphens, underscores, spaces, and periods.
ISO 8601 timestamp when the key should expire. If not provided, the key doesn’t expire.
Maximum number of tokens this key can use. If not provided, no limit is enforced.
Custom metadata to attach to the key. Maximum size: 5KB.
Example Request
Response
Update API Key
Updates an existing regular API key in your organization. You can update any non-admin key in the organization, provided you have the full key value.
Request Body
The API key value to update, as returned by
GET /api/keys.New display name for the API key.
New token cap for the key. Set this to
0 to clear the existing cap.Example Request
Response
Delete API Key
Deletes a regular API key in your organization. You can delete any non-admin key, provided you have the full key value.
Path Parameters
The API key value to delete (for example,
tk_your_full_key_value_here).Example Request
Response
Billing & Usage
Get Usage Statistics
Retrieves aggregated usage statistics for your organization for the specified time period.
Query Parameters
Time period for usage statistics. If omitted, returns all-time usage. Valid values:
5m- Last 5 minutes15m- Last 15 minutes30m- Last 30 minutes1h- Last hour24h- Last 24 hours7d- Last 7 days30d- Last 30 days60d- Last 60 days90d- Last 90 days
Example Request
Response
keys object is grouped by API key name.
Get Usage by Key
Retrieves usage statistics for a specific regular API key in your organization.
Query Parameters
Time period for usage statistics. If omitted, returns all-time usage. Valid values:
5m- Last 5 minutes15m- Last 15 minutes30m- Last 30 minutes1h- Last hour24h- Last 24 hours7d- Last 7 days30d- Last 30 days60d- Last 60 days90d- Last 90 days
Request Body
The API key value to query (for example,
tk_your_full_key_value_here), as returned by GET /api/keys.Example Request
Response
Get Time Series Data
Retrieves time-series usage data for your organization over the specified period.
Query Parameters
Time period for the time series. Valid values:
5m- Last 5 minutes15m- Last 15 minutes30m- Last 30 minutes1h- Last hour24h- Last 24 hours7d- Last 7 days30d- Last 30 days60d- Last 60 days90d- Last 90 days
5m → 5s, 15m → 15s, 30m → 30s, 1h → 1m, 24h → 15m, 7d → 2h, 30d → 8h, and 60d/90d → 24h. Empty buckets are included as zero-value data points.
Example Request
Response
Get Transaction History
Retrieves invoice and standalone charge history for your organization.
Example Request
Response
Containers
Admin API keys can access the same container APIs as a browser session, as long as the key belongs to the target organization.Create, start, and relaunch operations require an active container subscription. Read-only endpoints and cleanup operations such as list, get, stop, and delete do not require an active subscription.
Private registry endpoints require private registry access to be enabled for the organization.
Lifecycle & Deployment
Validate Container Name
Checks whether a container name is valid and available for the current organization. You can also validate a custom domain before creating or relaunching a container.
Request Body
Container name. Must be lowercase alphanumeric with hyphens, max 64 characters.
Whether to validate the name for debug mode.
Custom domain to validate.
Existing container UUID when validating a relaunch that keeps the same custom domain.
Example Request
Response
Validate Container Config
Validates the
tinfoil-config.yml in a repository tag before create, replace, or relaunch.Request Body
GitHub repository in
owner/repo format.Git tag to validate.
Existing container UUID. When present, instance-limit checks are skipped for relaunch validation.
Existing container UUID. When present, instance-limit checks are skipped for replace validation.
List Hosts
Returns the container hosts available to the organization, including the default host and the GPU values available on each host.
Response
List Containers
Returns all containers in your organization. Responses may also include
ssh_port, host_name, host_gpu_type, and host_cpu_type when available.Example Request
Response
Get Container
Returns details for a specific container.
Path Parameters
The container UUID.
Example Request
Create Container
Creates and deploys a new container. The repository must contain a
tinfoil-config.yml at the specified tag.Request Body
Container name. Must be lowercase alphanumeric with hyphens.
GitHub repository in
owner/repo format.Git tag to deploy. The tag must have a published GitHub release.
Environment variables as key-value pairs.
Names of existing org secrets to inject.
Names of existing org SSH keys to inject.
Enable debug mode.
Enable docker log capture for the deployment.
Number of GPUs to allocate. Requires GPU access for the organization.
Verified custom domain for the container.
Target host name. Requires target host selection to be enabled for the organization.
Existing container UUID to replace.
Example Request
Response
Returns the created container object with statusdeploying. The container transitions to ready once the deployment completes.
Relaunch Container
Relaunches a running or failed container with a new tag, updated configuration, or both. Running single-GPU and CPU-only containers usually use a blue-green deployment flow. Multi-GPU updates use a different flow and cannot always be canceled once started.
Path Parameters
The container UUID.
Request Body
All fields are optional. Omitted fields keep their current values.New git tag to deploy.
New environment variables. This replaces the full existing variable set.
New secret-name list. This replaces the full existing secret set.
New SSH key-name list.
New GPU count.
Toggle debug mode.
Set or clear a custom domain. Pass an empty string to revert to the auto-generated domain.
Example Request
Stop Container
Stops a running container. The container record is preserved and can be started again later.
Start Container
Starts a stopped container. You can optionally pass the same body fields as relaunch to update configuration at start time.
Delete Container
Permanently deletes a container and its deployment. Outstanding billing is finalized before deletion.
204 No Content on success.
Get Update Status
Returns the status of an in-progress relaunch or restart.
Response
Cancel Update
Cancels an in-progress update and returns
204 No Content. Multi-GPU updates cannot be canceled once started.Toggle Auto-Update
Enables or disables auto-update for a GitHub App connected container.
Request Body
Whether auto-update should be enabled.
Toggle GitHub App Connection
Sets whether the container is connected to a GitHub App installation for its repo owner.
Request Body
Whether GitHub App connectivity should be enabled.
Get Container Metrics
Returns CPU, GPU, and memory utilization time series for a container. The
time query parameter defaults to 24h.Organization
These endpoints are also available to admin API keys:PUT /api/containers/:id/groupmoves a container into or out of a group withgroup_name,group_order, anddisplay_orderPUT /api/containers/reorderbulk-updates container display orderPUT /api/containers/groups/renamerenames a groupPUT /api/containers/groups/reorderupdates group orderDELETE /api/containers/groups/:nameremoves a group and ungroups its containers
Related Resources
Secrets
Org secrets are encrypted values injected into containers at deploy time. Secret names must beUPPER_SNAKE_CASE or kebab-case.
Returns all org-level secrets as metadata only. Secret values are never returned.
Returns metadata for a single secret, including which containers use it.
Creates a new org secret.
Request Body
Secret name.
Secret value.
Updates the value of an existing org secret.
Deletes an org secret. If the secret is currently used by any container, the API returns
409 Conflict and includes the blocking container names.SSH Keys
SSH key names must be kebab-case, for examplemy-deploy-key.
Returns all org-level SSH keys.
Adds a new org SSH key for debug-mode containers.
Request Body
SSH key name in kebab-case.
SSH public key, for example
ssh-ed25519 AAAA....Deletes an org SSH key. If the key is currently used by any container, the API returns
409 Conflict and includes the blocking container names.Custom Domains
Returns all custom domains for the organization, including verification details and which containers use each domain.
Adds a custom domain for verification and returns the TXT and CNAME records required for setup.
Request Body
Domain name to register, for example
api.example.com.Checks DNS records and updates the domain’s verification state.
Deletes a custom domain. If the domain is currently used by any container, the API returns
409 Conflict and includes the blocking container names.Registry Credentials
Private registry credentials are supported forghcr, gcr, and dockerhub.
Returns credential status for each supported registry, including whether credentials exist, whether they are expired, and when they were last updated.
Creates or updates credentials for a supported registry.
Path Parameters
Registry identifier:
ghcr, gcr, or dockerhub.Request Body
Forghcr:
gcr:
dockerhub:
Deletes credentials for a supported registry.
Error Responses
Example error response:| Code | HTTP Status | Description |
|---|---|---|
UNAUTHORIZED | 401 | Invalid or expired admin API key |
FORBIDDEN | 403 | Your admin key no longer has access to this organization or action |
BAD_REQUEST | 400 | Invalid request parameters |
NOT_FOUND | 404 | Resource not found, or the referenced API key is not available through this admin key |
PAYMENT_REQUIRED | 402 | Active subscription required |
INTERNAL_ERROR | 500 | Server error |

