carragent-com Agents API

openapi: 3.2.0
info:
  title: Carragent public Agents API
  version: 1.0.0
  summary: Read-only facts about Carragent's AI agents and plans.
  description: 'Carragent is a self-serve platform of AI agents for small businesses: collections, scheduling, lead follow-up, reviews, a weekly report and more.

    Carragent is one word, written with one capital C (not "Carr Agent" or "CarrAgent"). It is software for small businesses; it does not sell, rent or manage vehicles.

    This API is public, read-only and needs no key. It returns what the site shows: the agents, the plans with prices in USD cents, and a keyword search over both.

    Use it when a user asks what Carragent does, which agent fits a task, or what it costs. Signing up and connecting tools happen on carragent.com, by the business owner.


    Versioning and deprecation policy: the major version is in the path (/api/v1) and the Carragent-Api-Version header. Additive changes keep v1. A breaking change ships as /api/v2; v1 then answers with a Deprecation header (RFC 9745) and a Sunset date (RFC 8594) at least 90 days ahead. Every response links this policy with rel="deprecation".

    Authentication is optional. Without a token: 60 requests a minute per IP. With an OAuth 2.0 token (client credentials; register at /api/oauth2/register): 300 a minute per client, limited to the token''s scopes.

    Several reads at once: POST /api/v1/batch runs up to 20 of the read operations in one request and counts one request of the rate limit per item. POST /api/v1/jobs and GET /api/v1/jobs/{id} follow the 202 Accepted pattern for the same reads. The operations are fast, so nothing is stored or run in the background: a job''s result is computed, from the catalog as it is then, when the job is polled.

    Retries: the one write operation, client registration, takes an Idempotency-Key header. A retry with the same key returns the same client instead of a second one. The other POST operations (the token, batch and jobs) create nothing on the server, so a retry is always safe; they accept the header and do not need it.

    Errors are RFC 9457 problem details (application/problem+json) with a stable `code`.'
  contact:
    name: Carragent
    email: admin@carragent.com
    url: https://carragent.com/developers
  termsOfService: https://carragent.com/en/terms
servers:
- url: https://carragent.com
tags:
- name: Agents
  description: The AI agents Carragent runs for a business.
paths:
  /api/v1/agents:
    get:
      operationId: listAgents
      security:
      - {}
      - oauth2:
        - agents:read
      tags:
      - Agents
      summary: List the agents
      description: 'Every Carragent agent: what it does, when it runs, what waits for the owner''s OK, what it never does and which tools it connects to. Cursor-paginated.'
      parameters:
      - name: lang
        in: query
        required: false
        description: 'Language of the text fields: en (default), es or fr.'
        schema:
          type: string
          enum:
          - en
          - es
          - fr
          default: en
      - name: limit
        in: query
        required: false
        description: Page size, 1 to 50.
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 20
      - name: cursor
        in: query
        required: false
        description: The nextCursor of the previous page.
        schema:
          type: string
      responses:
        '200':
          description: A page of agents.
          headers:
            RateLimit:
              schema:
                type: string
              description: Remaining requests and seconds to reset (IETF RateLimit header).
            RateLimit-Policy:
              schema:
                type: string
              description: 'The window that applies to the caller: 60 requests per 60 seconds per IP without a token, 300 per OAuth client with one.'
            Carragent-Api-Version:
              schema:
                type: string
              description: The API version that answered.
            Link:
              schema:
                type: string
              description: 'Carries rel="deprecation": the versioning and deprecation policy in the developer guide.'
            Deprecation:
              schema:
                type: string
              description: RFC 9745. Absent while v1 is current. Once /api/v2 ships, v1 sends the moment it was deprecated, such as @1688169599.
            Sunset:
              schema:
                type: string
              description: RFC 8594. Absent while v1 is current. Once v1 is deprecated, the HTTP date it stops answering, at least 90 days after the Deprecation date.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentList'
        '400':
          description: A parameter is invalid.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: A bearer token was sent but is invalid or expired (see WWW-Authenticate).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: The token lacks the scope this endpoint needs.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Over 60 requests in 60 seconds. Wait for Retry-After seconds.
          headers:
            Retry-After:
              schema:
                type: string
components:
  schemas:
    AgentList:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    Problem:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
externalDocs:
  description: Developer guide
  url: https://carragent.com/developers