> ## Documentation Index > Fetch the complete documentation index at: https://docs.x402layer.cc/llms.txt > Use this file to discover all available pages before exploring further. # Create a pod (API key) > Base URL `https://compute.x402layer.cc/pods/v1`. Auth is `X-API-Key` only. This is the PROGRAMMATIC surface and is NOT the same as the dashboard pod routes (`POST /pods`, `PATCH /pods/{id}/settings`, ...), which take a wallet signature or a browser session and are free to change. Every response carries `x-request-id`. **`Idempotency-Key` is REQUIRED and the request is refused without it.** This call provisions a machine and charges for it. Replaying the same key returns the ORIGINAL response byte for byte with `Idempotent-Replay: true` and a `200` instead of a `201`, rather than making a second pod. The same key with a DIFFERENT body is a `409` carrying `details.code = idempotency_mismatch`, because that is a bug in your code and swallowing it would hide it. Use an id you already have - an order number, a job id. A generated UUID protects a retry inside one process; only a stable id protects a retry after that process dies. Returns `201` with `status: provisioning`. The machine takes a few minutes to boot; poll `GET /pods/v1/pods/{id}` until `status` is `online`. Rate limit: **60 creates per HOUR**, a separate and tighter bucket than ordinary writes, because this is the call that costs money. The idempotency key stops an accidental double-create; it does nothing about a deliberate loop, which is what this bucket is for. **Rate limit: 60 creates per hour**, a separate and tighter bucket than the 60/min write limit. This is the call that provisions a machine and charges for it, so a runaway loop costs money rather than a wasted query. The `Idempotency-Key` prevents an *accidental* double-create; it does nothing about a deliberate loop. ## OpenAPI ````yaml POST /pods/v1/pods openapi: 3.1.0 info: title: x402 Singularity Layer API description: >- OpenAPI-backed reference for marketplace discovery, payment routes, webhooks, wallet-first auth, agent endpoints, and ERC-8004 flows. version: 1.0.0 servers: - url: https://api.x402layer.cc security: [] tags: - name: Marketplace description: Public discovery and listing lookup - name: Public Endpoints description: Public endpoint metadata and hosted checkout context - name: Public Payment Links description: Hosted public payment-link lookup - name: Payments description: Hosted x402 payment challenge routes - name: Receipts description: Signed receipt lookup and verification helpers - name: Ratings description: Public listing ratings and authenticated rating actions - name: Webhooks description: Seller webhook management API - name: Agent Auth description: Wallet-first challenge and verification routes - name: Agent Endpoints description: Create, read, top up, and delete agent endpoints - name: ERC-8004 description: Agent registry and registration lifecycle routes - name: Marketplace Agents description: Public ERC-8004 marketplace discovery routes - name: Compute Catalog description: Compute plans, regions, and OS catalog - name: Compute Instances description: Provision, inspect, extend, and destroy compute instances - name: Compute API Keys description: API keys for compute agent access - name: Fundraiser Campaigns description: List, view, create, and edit fundraiser campaigns - name: Fundraiser Contributions description: Record and list campaign contributions - name: Fundraiser Comments description: Campaign comment threads - name: Fundraiser Media description: Campaign image uploads and OG images - name: Enterprise description: >- Enterprise partner configuration, endpoint listing, revenue stats, and transaction ledger - name: Staking description: Agentic $SGL staking - name: SGL Grid description: >- Decentralized, confidential, OpenAI-compatible inference served by attested TEE nodes. - name: Compute Credits description: Prepaid USDC credit balance shared across Machines and Grid. - name: Agent Pods description: >- Deploy and manage hosted agents (Agent Pods), plus the pod's OpenAI-compatible adapter for external clients. - name: Agent Pods API description: >- The programmatic `/pods/v1` surface: create, drive and destroy Agent Pods with a single `X-API-Key`. Distinct from the Agent Pods dashboard routes, which expect a wallet signature or a browser session. paths: /pods/v1/pods: servers: - url: https://compute.x402layer.cc post: tags: - Agent Pods API summary: Create a pod description: >- Base URL `https://compute.x402layer.cc/pods/v1`. Auth is `X-API-Key` only. This is the PROGRAMMATIC surface and is NOT the same as the dashboard pod routes (`POST /pods`, `PATCH /pods/{id}/settings`, ...), which take a wallet signature or a browser session and are free to change. Every response carries `x-request-id`. **`Idempotency-Key` is REQUIRED and the request is refused without it.** This call provisions a machine and charges for it. Replaying the same key returns the ORIGINAL response byte for byte with `Idempotent-Replay: true` and a `200` instead of a `201`, rather than making a second pod. The same key with a DIFFERENT body is a `409` carrying `details.code = idempotency_mismatch`, because that is a bug in your code and swallowing it would hide it. Use an id you already have - an order number, a job id. A generated UUID protects a retry inside one process; only a stable id protects a retry after that process dies. Returns `201` with `status: provisioning`. The machine takes a few minutes to boot; poll `GET /pods/v1/pods/{id}` until `status` is `online`. Rate limit: **60 creates per HOUR**, a separate and tighter bucket than ordinary writes, because this is the call that costs money. The idempotency key stops an accidental double-create; it does nothing about a deliberate loop, which is what this bucket is for. **Rate limit: 60 creates per hour**, a separate and tighter bucket than the 60/min write limit. This is the call that provisions a machine and charges for it, so a runaway loop costs money rather than a wasted query. The `Idempotency-Key` prevents an *accidental* double-create; it does nothing about a deliberate loop. parameters: - name: Idempotency-Key in: header required: true schema: type: string example: order-4471 description: >- REQUIRED. A stable id of your own. Replaying it returns the original response instead of creating a second pod. - name: x-request-id in: header required: false schema: type: string description: Optional correlation id, echoed back on the response. requestBody: required: true content: application/json: schema: type: object description: >- Only these fields are read. Anything else is ignored - internal pricing and provisioning fields are deliberately not forwardable from a public caller. properties: tier: type: string example: starter description: Capability/price tier. Defaults to `starter`. name: type: string maxLength: 120 description: Your display name for the pod. external_ref: type: string maxLength: 128 description: >- YOUR id. Comes back on every read and filters `GET /pods`, so you can find the pod again from your own database without storing ours. model: type: string description: >- Model slug. Managed pods clamp this to the tier's allowed list. system_prompt: type: string description: Initial system prompt for the agent. region: type: string description: >- Optional datacentre pin. Omit it and we choose - picking a datacentre is our job, not yours. term_hours: type: integer minimum: 24 default: 24 description: Prepaid runtime in hours. Minimum 24. capabilities: $ref: '#/components/schemas/PodV1Capabilities' ai: type: object description: >- `managed` = we run and meter the LLM. `byok` = the pod calls your own OpenAI-compatible endpoint. properties: mode: type: string enum: - managed - byok default: managed api_key: type: string description: BYOK only. Your provider key, stored encrypted. base_url: type: string description: BYOK only. Your OpenAI-compatible base URL. api: type: string description: BYOK only. Provider API type. responses: '200': description: >- Idempotent replay: this exact `Idempotency-Key` already created a pod, so the ORIGINAL response body is returned unchanged. `200`, not `201` - the pod was created by the earlier call. headers: x-request-id: description: >- Correlation id for this request. A caller-supplied `x-request-id` (8-64 chars of `A-Za-z0-9._-`) is echoed back; otherwise one is generated. Quote it in support requests. schema: type: string Idempotent-Replay: description: '`true` when this body is a replay of an earlier create.' schema: type: string enum: - 'true' content: application/json: schema: type: object properties: pod: $ref: '#/components/schemas/PodV1' '201': description: Pod created. `status` is `provisioning`. headers: x-request-id: description: >- Correlation id for this request. A caller-supplied `x-request-id` (8-64 chars of `A-Za-z0-9._-`) is echoed back; otherwise one is generated. Quote it in support requests. schema: type: string content: application/json: schema: type: object properties: pod: $ref: '#/components/schemas/PodV1' '400': description: >- `invalid_request` - missing or malformed `Idempotency-Key`, or an invalid body. headers: x-request-id: description: >- Correlation id for this request. A caller-supplied `x-request-id` (8-64 chars of `A-Za-z0-9._-`) is echoed back; otherwise one is generated. Quote it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/PodV1Error' '401': description: '`unauthorized` - missing or invalid `X-API-Key`.' headers: x-request-id: description: >- Correlation id for this request. A caller-supplied `x-request-id` (8-64 chars of `A-Za-z0-9._-`) is echoed back; otherwise one is generated. Quote it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/PodV1Error' '402': description: >- Payment required. The create could not be funded from prepaid credits. headers: x-request-id: description: >- Correlation id for this request. A caller-supplied `x-request-id` (8-64 chars of `A-Za-z0-9._-`) is echoed back; otherwise one is generated. Quote it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/PodV1Error' '409': description: >- `conflict` with `details.code = idempotency_mismatch` (same key, different body), `idempotency_in_progress`, or `needs_review`; or `limit_exceeded` when the account is at its live-pod cap. headers: x-request-id: description: >- Correlation id for this request. A caller-supplied `x-request-id` (8-64 chars of `A-Za-z0-9._-`) is echoed back; otherwise one is generated. Quote it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/PodV1Error' '413': description: '`invalid_request` - request body over the 128 KB limit.' headers: x-request-id: description: >- Correlation id for this request. A caller-supplied `x-request-id` (8-64 chars of `A-Za-z0-9._-`) is echoed back; otherwise one is generated. Quote it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/PodV1Error' '429': description: '`rate_limited` - more than 60 creates in an hour.' headers: x-request-id: description: >- Correlation id for this request. A caller-supplied `x-request-id` (8-64 chars of `A-Za-z0-9._-`) is echoed back; otherwise one is generated. Quote it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/PodV1Error' '503': description: >- `rate_limited` or `internal` - the platform is at capacity for this beta, or creation is not configured. headers: x-request-id: description: >- Correlation id for this request. A caller-supplied `x-request-id` (8-64 chars of `A-Za-z0-9._-`) is echoed back; otherwise one is generated. Quote it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/PodV1Error' security: - podsApiKey: [] components: schemas: PodV1Capabilities: type: object description: >- What this pod was provisioned with. Omitting `capabilities` on create gives every capability. properties: endpoint: type: boolean description: OpenAI-compatible endpoint and pod endpoint keys. wallet: type: boolean description: The pod's own Base + Solana wallet. platform_tools: type: boolean description: Singularity platform MCP tools on the pod. connectors: type: boolean description: Owner-added MCP connectors. channels: type: boolean description: Messaging channels (Telegram, ...). scheduler: type: boolean description: Scheduled tasks. backups: type: boolean description: Agent Vault automatic backups. PodV1: type: object description: >- The public projection of a pod on `/pods/v1`. An allowlist: it never carries the engine, its version, the provider, the region, the machine plan, the IP, or any credential, so the pod's implementation can change without breaking your integration. properties: id: type: string format: uuid description: Pod id. Use it on every `/pods/v1/pods/{id}/*` route. name: type: string nullable: true description: Your display name for the pod. slug: type: string nullable: true description: >- Vanity endpoint slug, when one is set. It appears in the pod's OpenAI base URL, so it is a different thing from `name`. external_ref: type: string nullable: true description: >- YOUR id, echoed back on every read and usable as a filter on `GET /pods`. Store this instead of ours. status: type: string enum: - provisioning - online - offline - grace - destroying - destroyed description: >- Engine-neutral lifecycle state. `destroying` means teardown is accepted but the machine may still be running, and may still bill for a few minutes. tier: type: string nullable: true example: starter model: type: string nullable: true description: The model the pod runs. ai: type: object properties: mode: type: string enum: - managed - byok capabilities: $ref: '#/components/schemas/PodV1Capabilities' endpoint: type: object nullable: true description: >- Null when the pod has no `endpoint` capability - there genuinely is no URL then. properties: base_url: type: string example: https://compute.x402layer.cc/pods/{id}/v1 billing: type: object properties: expires_at: type: string format: date-time nullable: true auto_renew: type: boolean nullable: true is_trial: type: boolean created_at: type: string format: date-time nullable: true PodV1Error: type: object description: >- Every `/pods/v1/*` failure has this shape. Branch on `error.code`, never on `error.message` - the message is prose and may be reworded. properties: error: type: object required: - code - message properties: code: type: string enum: - invalid_request - unauthorized - forbidden - not_found - conflict - limit_exceeded - capability_disabled - rate_limited - not_implemented - internal description: Stable machine-readable code. message: type: string description: Human-readable explanation. details: type: object description: >- Optional structured context, e.g. `{ "code": "idempotency_mismatch" }`, `{ "required_scope": "pods:wallet:write" }`, `{ "capability": "wallet" }`, `{ "retry_after_seconds": 60 }`. securitySchemes: podsApiKey: type: apiKey in: header name: X-API-Key description: >- A compute API key (`x402c_...`). Mint one in the dashboard under Settings -> API Keys. This is the ONLY auth `/pods/v1/*` accepts - wallet signatures are bound to method+path+body and do not survive the internal hop, so signature callers must use the dashboard routes instead. Two extra scopes gate the dangerous powers: `pods:wallet:write` (pod wallet money, backup passphrase) and `pods:control:write` (connectors, full-power control socket). ````