pricklymails-com Agents API

openapi: 3.2.0
info:
  title: Pricklymails Com Agents API
  version: 0.9.0
  contact:
    email: support@pricklymails.com
  license:
    name: Proprietary
  description: 'Operations tagged agents across 2 of this provider''s published API definitions: pricklymails-com-openapi.json, pricklymails-com-openapi.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: Agents
  description: The AI agents allowed to act on your account, each with its own scopes.
paths:
  /api/agents:
    get:
      tags:
      - Agents
      summary: Lists the agents of the authenticated account, newest first, paginated
      description: A `limit` outside 1 to 96 is clamped to that range.
      operationId: list_agents
      parameters:
      - name: limit
        in: query
        description: Number of agents to return (default 20, cap 96).
        required: false
        schema:
          type: integer
          format: int64
      - name: offset
        in: query
        description: Number of agents to skip (default 0).
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Paginated agent list, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentsResponse'
        '401':
          description: Missing or invalid JWT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - jwt: []
    post:
      tags:
      - Agents
      summary: Creates an agent for the authenticated account, with its own granted scopes
      description: 'An agent has no API key of its own: it is authorized through OAuth, with the scopes granted here. When `scopes` is omitted, the default scopes for the account''s plan apply. The number of agents and the scopes an agent may hold depend on the account''s plan.'
      operationId: create_agent
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
        required: true
      responses:
        '201':
          description: Agent created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCreatedResponse'
        '400':
          description: Invalid name or scopes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Missing or invalid JWT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '403':
          description: The plan's agent cap was reached, or a requested scope is not allowed for the caller's plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - jwt: []
  /api/agents/{uuid}:
    get:
      tags:
      - Agents
      summary: Returns one agent of the authenticated account
      operationId: get_agent
      parameters:
      - name: uuid
        in: path
        description: Public UUID of the agent.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '400':
          description: Malformed uuid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Missing or invalid JWT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '404':
          description: No agent with that uuid owned by the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - jwt: []
    delete:
      tags:
      - Agents
      summary: Revokes an agent so it can no longer authenticate
      description: 'Idempotent: revoking an already revoked agent returns it unchanged, with status `revoked`.'
      operationId: revoke_agent
      parameters:
      - name: uuid
        in: path
        description: Public UUID of the agent.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The revoked agent (idempotent on repeat calls).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '400':
          description: Malformed uuid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '401':
          description: Missing or invalid JWT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
        '404':
          description: No agent with that uuid owned by the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorBody'
      security:
      - jwt: []
components:
  schemas:
    ApiErrorBody:
      type: object
      description: 'Error envelope returned with every non-success status: `{ "error": { "code", "message" } }`.'
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorDetail'
          description: Error detail.
    CreateAgentRequest:
      type: object
      description: '`POST /api/agents` request body.'
      required:
      - name
      properties:
        description:
          type:
          - string
          - 'null'
          description: Free-text description of the agent.
        name:
          type: string
          description: Display name of the agent (at most 128 characters).
        scopes:
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'Scopes to grant, for example `"email:verify:single"`. Must be allowed by the account''s plan.

            Defaults to the plan''s default agent scopes when absent.'
    AgentResponse:
      type: object
      description: 'Metadata of an agent, returned when creating, listing, reading or revoking agents.

        `scopes` lists the permissions granted directly to the agent, which has no API key of its own.'
      required:
      - uuid
      - name
      - status
      - is_active
      - scopes
      - created_at
      - updated_at
      properties:
        created_at:
          type: string
          description: RFC 3339 creation timestamp.
        description:
          type:
          - string
          - 'null'
          description: Description of the agent, omitted when none was set.
        is_active:
          type: boolean
          description: Whether the agent can currently authenticate.
        name:
          type: string
          description: Display name of the agent.
        scopes:
          type: array
          items:
            type: string
          description: Scopes granted to the agent.
        status:
          type: string
          description: 'Status of the agent: `"active"` or `"revoked"`.'
        updated_at:
          type: string
          description: RFC 3339 timestamp of the last change.
        uuid:
          type: string
          description: Public UUID of the agent.
    ApiErrorDetail:
      type: object
      description: Detail of an error response.
      required:
      - code
      properties:
        code:
          type: string
          description: Stable key identifying the error (for example `"verify.invalid_uuid"`). Clients localize by this key.
        message:
          type:
          - string
          - 'null'
          description: 'Present on most error kinds and equal to `code`; the API returns no localized text.

            Absent for error kinds that carry no extra detail.'
    AgentCreatedResponse:
      type: object
      description: '`POST /api/agents` response body.

        An agent has no API key, so no secret is returned.'
      required:
      - agent
      properties:
        agent:
          $ref: '#/components/schemas/AgentResponse'
          description: The new agent, including the scopes just granted to it.
    ListAgentsResponse:
      type: object
      description: '`GET /api/agents` response body: a paginated page of the caller''s agents.'
      required:
      - agents
      - limit
      - offset
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentResponse'
          description: The caller's agents, newest first.
        limit:
          type: integer
          format: int64
          description: Page size applied after clamping.
        offset:
          type: integer
          format: int64
          description: Offset applied.
  securitySchemes:
    bearer_api_key:
      type: http
      scheme: bearer
      description: A `pm_live_*` or `pm_test_*` API key.
    jwt:
      type: http
      scheme: bearer
      description: A short-lived token from `/api/auth/login`, or `/oauth/token` for an agent.
x-refined-from:
- pricklymails-com-openapi.json
- pricklymails-com-openapi.yaml