> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add capacity

> Add computers to the account, charged to the card on file.

Adds `count` computers of `size` to the account, at the same prices as the Plan tab. The charge for the rest of the current period is made now, and the full amount joins every renewal after it.

```bash theme={null}
curl -X POST https://www.orgo.ai/api/account/capacity \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "size": "medium", "count": 100 }'
```

## Price it first

Send `dry_run: true` to see the charge without making it:

```json theme={null}
{ "size": "medium", "count": 100, "dry_run": true }
```

```json theme={null}
{
  "dry_run": true,
  "size": "medium",
  "count": 100,
  "os": "linux",
  "term": "monthly",
  "monthly_usd": 2500,
  "due_now_usd": 1650,
  "next_invoice_usd": 4149,
  "next_invoice_at": "2026-11-01T00:00:00.000Z"
}
```

## Retries never buy twice

Send an `Idempotency-Key` header, a new UUID per purchase. If the connection drops before the answer arrives, retry with the same key and body: you get the first answer back, marked `Idempotent-Replayed: true`, and nothing is bought again.

| Answer | Meaning |
| - | - |
| `409` `idempotency_in_progress` | The first request is still running. Retry in a few seconds. |
| `409` `idempotency_unfinished` | The first request did not finish and may have charged. Check [Get capacity](/api-reference/account/capacity) before trying again with a new key. |
| `422` `idempotency_key_reused` | The key was already used for a different body. |

## The self-serve cap

Every account can add up to 30 computers on its own (with up to 800 GB RAM, 50 vCPU and 2 TB of disk across them). Past that, a purchase returns `403` with code `capacity_cap`, naming the limit:

```json theme={null}
{
  "error": "That would go past this account's limit of 30 extra computers. Ask us to raise it.",
  "code": "capacity_cap",
  "self_serve_cap": { "computers": 30, "ram_gb": 800, "vcpu": 50, "disk_gb": 2000 }
}
```

[Ask us](mailto:support@orgo.ai) and we raise the cap for the account, to thousands of computers if you need them. Nothing else about the account changes.


## OpenAPI

````yaml POST /account/capacity
openapi: 3.1.0
info:
  title: Orgo API
  description: >-
    Launch cloud computers that AI agents can control and interact with. Create
    workspaces, provision computers, and control them programmatically.
  version: 2.0.0
  contact:
    name: Orgo Support
    email: spencer@orgo.ai
    url: https://orgo.ai
servers:
  - url: https://www.orgo.ai/api
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: >-
      Account capacity: how many computers an account may run, and adding or
      giving back more.
  - name: Workspaces
    description: Organize computers into named workspaces
  - name: Computers
    description: Provision and manage virtual computers
  - name: Computer Lifecycle
    description: Start, stop, and restart computers
  - name: Computer Actions
    description: Control mouse, keyboard, and execute commands
  - name: Screens
    description: >-
      More than one desktop on a single computer. Each screen is its own X
      server with its own cursor and window manager, so an agent working on one
      cannot disturb another.
  - name: Files
    description: Upload and download files
  - name: Templates
    description: Author, build, and launch reproducible computers from templates
paths:
  /account/capacity:
    post:
      tags:
        - Account
      summary: Add capacity
      description: >-
        Adds `count` computers of `size` to the account, charged to the card on
        file at the same prices as the Plan tab. Send `dry_run: true` to see the
        charge without making it. Send an `Idempotency-Key` header with every
        purchase: a retry with the same key returns the first answer (with
        `Idempotent-Replayed: true`) and never buys twice.
      operationId: addAccountCapacity
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            A unique value per purchase, such as a UUID (8 to 255 printable
            characters). Keys last 24 hours.
          schema:
            type: string
            minLength: 8
            maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - size
                - count
              properties:
                size:
                  type: string
                  enum:
                    - small
                    - medium
                    - large
                    - xl
                    - 2xl
                  description: The size of each computer.
                count:
                  type: integer
                  minimum: 1
                  maximum: 500
                  description: How many computers to add.
                os:
                  type: string
                  enum:
                    - linux
                    - windows
                  default: linux
                  description: >-
                    `windows` adds a Windows license per computer, when
                    `windows_available` is true.
                term:
                  type: string
                  enum:
                    - monthly
                    - yearly
                  default: monthly
                  description: Billing term, from `terms`.
                dry_run:
                  type: boolean
                  default: false
                  description: Price the purchase without making it.
              additionalProperties: false
            example:
              size: medium
              count: 100
      responses:
        '200':
          description: >-
            Added, with the account's capacity after it. For `dry_run`:
            `monthly_usd`, `due_now_usd`, `next_invoice_usd` and
            `next_invoice_at`, and nothing is charged.
          content:
            application/json:
              schema:
                type: object
                properties:
                  added:
                    type: object
                    properties:
                      size:
                        type: string
                      count:
                        type: integer
                      os:
                        type: string
                      term:
                        type: string
                  capacity:
                    $ref: '#/components/schemas/AccountCapacity'
        '400':
          description: >-
            Invalid request (`invalid_request`, `invalid_idempotency_key`,
            `term_unavailable`, `windows_unavailable`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
        '402':
          description: >-
            No paid plan (`no_subscription`), or the card on file was declined
            (`card_declined`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
        '403':
          description: >-
            Past the account's self-serve cap (`capacity_cap`; the body names
            the limit and includes `self_serve_cap`), or a workspace-scoped key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
        '409':
          description: >-
            A request with this Idempotency-Key is still running
            (`idempotency_in_progress`), or did not finish
            (`idempotency_unfinished`: check the account before retrying with a
            new key).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
        '422':
          description: >-
            This Idempotency-Key was already used for a different request
            (`idempotency_key_reused`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
        '429':
          description: Rate limited. Retry after the `Retry-After` header.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
components:
  schemas:
    AccountCapacity:
      type: object
      properties:
        plan:
          type: string
          description: The account's plan, such as `startup_v2`.
        computers:
          type: object
          description: >-
            How many computers the account may run (its plan plus what it has
            added) and runs.
          properties:
            limit:
              type: integer
            in_use:
              type: integer
        ram_gb:
          type: object
          description: The account-wide RAM pool and what its computers use.
          properties:
            limit:
              type: number
            in_use:
              type: number
        added:
          type: object
          properties:
            computers:
              type: integer
            ram_gb:
              type: number
            vcpu:
              type: number
            disk_gb:
              type: number
          description: What the account has added beyond its plan.
        self_serve_cap:
          type: object
          properties:
            computers:
              type: integer
            ram_gb:
              type: number
            vcpu:
              type: number
            disk_gb:
              type: number
          description: >-
            The most the account may add on its own. Past it, purchases return
            `403` `capacity_cap`; ask us and we raise it for the account.
        can_add:
          type: object
          description: >-
            How many more computers of each size the account may add now, under
            its cap.
          properties:
            small:
              type: integer
            medium:
              type: integer
            large:
              type: integer
            xl:
              type: integer
            2xl:
              type: integer
        max_per_request:
          type: integer
          description: The most computers one purchase may add (500).
        sizes:
          type: array
          items:
            type: object
            properties:
              size:
                type: string
                enum:
                  - small
                  - medium
                  - large
                  - xl
                  - 2xl
              ram_gb:
                type: number
              vcpu:
                type: number
              disk_gb:
                type: number
              monthly_usd:
                type: number
        terms:
          type: array
          items:
            type: string
            enum:
              - monthly
              - yearly
        windows_available:
          type: boolean
        has_subscription:
          type: boolean
        renews_at:
          type:
            - string
            - 'null'
          format: date-time
        scheduled_reduction:
          type:
            - object
            - 'null'
          properties:
            added_computers:
              type: integer
            effective_at:
              type: string
              format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Get your key at orgo.ai/workspaces

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.