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

# Create an agent in the current workspace

> Creates an agent with a unique lowercase identifier in the current workspace. Choose its kind to run it on your own machine or as a hosted agent.

Creates a new agent. The `kind` field picks where it runs: `byo` (the default) runs on your machine and routes through the gateway, while `hosted` runs in Buckle. See [Coding agents](/docs/guides/coding-agents.md) to connect a `byo` agent.

Creates an agent in the current workspace. The identifier must be lowercase alphanumeric with hyphens, starting with a letter or digit (max 50 characters), and unique in the workspace.

`kind` picks the agent's home: `byo` (default) runs on your own machine and routes through the gateway; `hosted` runs in a Buckle sandbox and needs a runner to be online. `harness` and `instructions` apply to hosted agents only.

A new agent is attached to every workspace connection, custom secret, and LLM key automatically, so it can work right away; adjust with the Grants endpoints. The response's `llmKeys` lists the LLM keys it received — empty means the workspace has none yet.

The response omits the access token — read it from `GET /agents` or regenerate it with `POST /agents/{agentId}/regenerate-token`. Re-creating an existing identifier answers `409`.

> [!NOTE]
>
> **Availability:** Cloud · Community (self-hosted) · Enterprise (self-hosted)


## OpenAPI

````yaml /openapi.yaml post /agents
openapi: 3.1.0
info:
  title: Buckle API
  version: '1.0'
  description: >
    The Buckle API manages everything behind the gateway: workspaces, agents and
    what each agent may use (grants), secrets, app connections, organization
    policy, hosted-agent conversations, schedules, memory, skills, Slack
    channels, and the organization's directory.


    **Base URL:** `https://api.buckle.dev/v1` (Buckle Cloud) or
    `http://localhost:10254/v1` (self-hosted).


    ## Authentication


    Every endpoint takes an `Authorization: Bearer <token>` header unless its
    description says otherwise.


    - **Workspace API key** (`oc_…`) — acts inside one workspace. Read it from
    the dashboard or `GET /user/api-key`.

    - **Organization API key** (`oc_org_…`) — acts for the whole organization.
    Workspace-scoped endpoints additionally need an `X-Workspace-Id` header
    naming the workspace; without it they answer `401`.

    - **Dashboard session** — the browser's own session (Cloud: a bearer JWT;
    self-hosted: the session cookie).


    `X-Workspace-Id` replaced `X-Project-Id`. The old header, the `?_project`
    query bridge, and the `/v1/projects` path alias still work for a deprecation
    window and answer with a `Deprecation: true` header; migrate to the new
    names.


    ## Editions


    Each endpoint states where it is available. Unless marked otherwise an
    endpoint exists on **Buckle Cloud**, the **Community** self-hosted edition,
    and the **Enterprise** self-hosted edition. Endpoints tagged **Enterprise**
    answer `403` with `error.type: "enterprise_license_required"` on a
    self-hosted deployment that has not set `ENTERPRISE_ENABLED=true`; on Cloud
    they are always present, though some features are additionally gated by the
    organization's plan. Endpoints tagged **Cloud** do not exist on self-hosted
    deployments at all.


    ## Roles


    Organization-level endpoints (`/org/…`) require the **admin** or **owner**
    role wherever roles are enforced (Cloud and Enterprise). The Community
    edition runs a flat team: every active member passes the role check.
servers:
  - url: https://api.buckle.dev/v1
    description: Buckle Cloud
  - url: http://localhost:10254/v1
    description: Self-hosted
security:
  - bearerAuth: []
tags:
  - name: Workspaces
    description: >-
      Workspaces partition an organization's agents, secrets, and connections.
      Every workspace-scoped endpoint resolves its workspace from the API key
      (or `X-Workspace-Id` with an organization key).
  - name: Agents
    description: >-
      Manage agents, their gateway access tokens, and hosted-agent
      configuration.
  - name: Grants
    description: >-
      Which credentials each agent may use — attach app connections (with
      optional per-tool allow/approval lists and resource scoping) and secrets.
      Writes take effect immediately.
  - name: Secrets
    description: >-
      Credentials the gateway injects into outbound requests that match a host
      pattern.
  - name: Apps
    description: >-
      The app catalog, OAuth and direct-credential connects, your own OAuth
      client configuration, permission catalogs, and blocklists.
  - name: Connections
    description: Connected app accounts as a top-level resource.
  - name: Effective policy
    description: >-
      Read-only reflections of what the enforced policy means for an agent, a
      connection, or an app — workspace grants composed with organization rules.
  - name: Conversations
    description: >-
      Talk to a hosted agent. A conversation owns its turns, transcript, and
      attachments.
  - name: Schedules
    description: Cron-style schedules on a hosted agent.
  - name: Memories
    description: A hosted agent's memory files and their revision history.
  - name: Skills
    description: >-
      Skills reachable from a workspace — the organization's, the workspace's
      own, and per-agent ones.
  - name: Channels
    description: >-
      Where a hosted agent is reachable (Slack), who may reach it, who it may
      message, and which other agents it may talk to.
  - name: Approvals
    description: Long-poll for the gateway's manual-approval requests and submit decisions.
  - name: User
    description: Your profile, API keys, SSH keys, and account deletion.
  - name: Instance
    description: Unauthenticated deployment facts and bootstrap endpoints.
  - name: Utility
    description: Counts, vaults, and agent bootstrap helpers.
  - name: Organization
    description: The current organization and its invitations. Free on every edition.
  - name: Organization secrets
    description: Secrets shared into every workspace of the organization.
  - name: Organization policy
    description: >-
      The organization's first-match rule set — blocks, allows, rate limits,
      approvals, and app permissions that bind every workspace.
  - name: Organization connections
    description: App connections shared into every workspace of the organization.
  - name: Organization apps
    description: >-
      Connect apps and configure your own OAuth clients at the organization
      level.
  - name: Organization skills
    description: Skills every workspace in the organization receives.
  - name: Organization channels
    description: The organization's Slack integration and identity links.
  - name: Organization approvals
    description: Long-poll for manual-approval requests across every workspace.
  - name: Members
    description: The organization directory — list, provision, suspend, and remove members.
  - name: Groups
    description: Directory groups and group-to-role mappings.
  - name: Workspace access
    description: Share a workspace with people and groups.
  - name: Domains
    description: Verified email domains, the anchor for SSO and home-realm discovery.
  - name: SSO
    description: SAML and OIDC sign-in connections and organization-wide enforcement.
  - name: SCIM tokens
    description: Bearer tokens for the organization's SCIM endpoint.
  - name: App availability
    description: Restrict which apps each workspace may connect.
  - name: Provisioning
    description: >-
      Pre-create members with a ready workspace and API key, then let them claim
      the account.
  - name: Resource browsing
    description: Browse a connected account's folders to pick resource scopes for a grant.
  - name: SCIM
    description: >-
      The SCIM 2.0 provisioning endpoint for identity providers (Okta, Entra ID,
      and others).
paths:
  /agents:
    post:
      tags:
        - Agents
      summary: Create an agent
      description: >
        Creates an agent in the current workspace. The identifier must be
        lowercase alphanumeric with hyphens, starting with a letter or digit
        (max 50 characters), and unique in the workspace.


        `kind` picks the agent's home: `byo` (default) runs on your own machine
        and routes through the gateway; `hosted` runs in a Buckle sandbox and
        needs a runner to be online. `harness` and `instructions` apply to
        hosted agents only.


        A new agent is attached to every workspace connection, custom secret,
        and LLM key automatically, so it can work right away; adjust with the
        Grants endpoints. The response's `llmKeys` lists the LLM keys it
        received — empty means the workspace has none yet.


        The response omits the access token — read it from `GET /agents` or
        regenerate it with `POST /agents/{agentId}/regenerate-token`.
        Re-creating an existing identifier answers `409`.
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - identifier
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  example: Claude Assistant
                identifier:
                  type: string
                  pattern: ^[a-z0-9][a-z0-9-]{0,49}$
                  example: claude-assistant
                kind:
                  type: string
                  enum:
                    - byo
                    - hosted
                  default: byo
                harness:
                  type: string
                  description: Hosted agents only. The agent runtime; omit for the default.
                instructions:
                  type: string
                  maxLength: 20000
                  description: Hosted agents only. The agent's standing brief.
                parentIdentifier:
                  type: string
                  pattern: ^[a-z0-9][a-z0-9-]{0,49}$
                  deprecated: true
                  description: >-
                    Accepted for older CLIs that send it on sub-agent creation;
                    ignored by the server.
      responses:
        '201':
          description: Agent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCreated'
        '400':
          description: >-
            Validation error (including `harness`/`instructions` on a `byo`
            agent)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The organization's agent quota is reached, or this kind of agent
            cannot be created for the organization (Cloud)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: An agent with this identifier already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: No runner is available to host the agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AgentCreated:
      type: object
      description: >-
        `POST /agents` response. The access token is not included; read it from
        `GET /agents` or mint a new one with `POST
        /agents/{agentId}/regenerate-token`.
      properties:
        id:
          type: string
        name:
          type: string
        identifier:
          type: string
        kind:
          type: string
          enum:
            - byo
            - hosted
        harness:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        instructions:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        llmKeys:
          type: array
          items:
            type: string
          description: >-
            Secret ids of the LLM keys attached to the new agent automatically.
            Empty means the workspace has no LLM key yet.
    Error:
      description: >
        Error responses take one of two shapes depending on the failing layer:
        route-level validation returns the flat shape (`{ "error": "..." }`),
        while authentication failures and service errors return the envelope (`{
        "error": { "message": "...", "type": "..." } }`).
      oneOf:
        - $ref: '#/components/schemas/ErrorFlat'
        - $ref: '#/components/schemas/ErrorEnvelope'
    ErrorFlat:
      type: object
      description: Flat error shape used by route-level validation.
      required:
        - error
      properties:
        error:
          type: string
    ErrorEnvelope:
      type: object
      description: >-
        Envelope error shape used for authentication failures and service
        errors.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
              description: >-
                Error category: `authentication_error`, `invalid_request_error`,
                `not_found_error`, `validation_error`, `rate_limit_error`,
                `enterprise_license_required`, or `api_error`.
            code:
              type: string
              description: >-
                Present on some `401`s (for example when the organization
                requires SSO).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A workspace API key (`oc_…`) or organization API key (`oc_org_…`).
        Workspace-scoped endpoints called with an organization key also need
        `X-Workspace-Id`.

````

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