John\'s Essentials Agent API

openapi: 3.2.0
info:
  contact:
    email: support@johnsessentials.com
    name: John's Essentials Support
    url: https://johnsessentials.com
  description: 'Programmatic access to every tool on John''s Essentials. Compress PDFs,

    convert images, OCR documents, run AI agents that orchestrate any of

    the above — all behind a single bearer-token API key. ## Authentication

    All endpoints under `/api/v1/public/*` require a bearer token whose

    value is an API key starting with `je_live_sk_`. Generate keys in

    the dashboard at `/integrations?tab=api-keys`. ## Rate limits

    Tier-based limits are enforced per key on a 1-hour sliding window. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`,

    and `X-RateLimit-Reset`. 429 responses include the standard

    `Retry-After` header. ## Credits

    Every tool call spends the tool''s published credit price from your

    account''s monthly allowance — the same credits and the same prices

    the website charges (Starter 1,500 / Business 40,000 a month). The

    price of each tool is the `credits` field on `GET /tools`. Tool

    responses carry `X-Credits-Cost` (what this call cost) and

    `X-Credits-Remaining` (credits left this month, or `unlimited`). `GET /usage` is the meter: credits used and left this month, when

    the allowance resets and what each API key spent; it spends

    nothing. When

    the allowance is spent the call fails with 402 `file_limit_reached`;

    the body names the call''s cost (`credits`) and carries

    `add_credits_url`. Credit packs (500 for $7, 5,000 for $25, 25,000

    for $59) are bought on the billing page, top up the website and the

    API alike, and stay spendable for twelve months. Free accounts also

    have a daily cap of 100 credits (402 `daily_limit_reached`, with

    `resets_at_utc`); a pack does not lift that cap, a paid plan does. Agent runs additionally draw on the key''s monthly USD budget for

    model tokens (`cost_cap_exceeded`). ## Idempotency

    Send `Idempotency-Key: ` on any unsafe request

    (POST/PUT/PATCH) to make retries safe. Identical key + body within

    24h replays the cached response and adds `Idempotency-Replayed: true`. Reusing a key with a different body returns 409 `idempotency_key_in_use`. ## Errors

    All error responses share the same shape:

    ```json

    { "error": { "code": "auth_invalid_key",

    "message": "Invalid API key",

    "doc_url": "https://docs.johnsessentials.com/api/errors#auth_invalid_key",

    "request_id": "uuid" } }

    ```

    The full error catalogue is at `/api/errors`. ## Schema extensions (keys beginning `x-`)

    A tool''s `parameters_schema` is the JSON Schema describing its inputs. Some properties in it also carry keys beginning `x-` — today `x-ui` and

    `x-show-when`. These are presentation hints: instructions to our own web

    interface about labelling, units, and which controls to hide. They are not

    part of the API contract, so they may be added, changed, or removed at any

    time, without a new API version and without a deprecation notice. An `x-` key never changes the value a parameter accepts or returns. `type`, `enum`, `minimum`, `maximum`, `default` and `required` are

    authoritative. `x-ui.wire_scale` is the unit our form displays, not the

    unit the API accepts. `x-ui.unit_from` names another parameter whose

    value decides the unit and range our form shows for this one — a corner

    radius read as pixels up to 5000, or as a percentage up to 50 — and it

    only ever narrows the declared `minimum` and `maximum`, which remain

    what the API accepts. `x-show-when` says when our interface hides a

    control, never whether the API accepts it — a parameter our interface

    never shows is still accepted. `x-ui.draw` says which part of a drawing

    a parameter is (see `x-draw` below): our interface sets it by drawing on

    the file instead of typing it, and writes the same value the parameter

    accepts. Three `x-` keys sit on the schema itself, beside `properties` and

    `required`, and describe the tool rather than one parameter. They are

    advisory in the same way: our own interface and plan checks read them,

    and the tool''s endpoint remains what decides.'
  license:
    name: Proprietary
    url: https://johnsessentials.com/license
  summary: Deterministic file-processing tools, AI agent orchestration, and a public REST surface for both.
  title: John's Essentials Agent API
  version: 1.0.0
servers:
- description: Production
  url: https://api.johnsessentials.com/api/v1
- description: Local development
  url: http://localhost:3000/api/v1
security:
- BearerAuth: []
tags:
- description: AI agent orchestration (tool calls, workflows, streaming)
  name: Agent
paths:
  /public/agent/conversations:
    get:
      description: 'Conversation threads persist across runs (retention by plan tier).

        Pass a conversation''s id as `conversation_id` in a run request to

        continue it with full context.'
      operationId: agentConversationsList
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: Conversations, newest first.
        '401':
          $ref: '#/components/responses/Unauthorized'
      summary: List saved agent conversations
      tags:
      - Agent
  /public/agent/conversations/{id}:
    delete:
      operationId: agentConversationDelete
      parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: Deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Delete a conversation and its turns
      tags:
      - Agent
    get:
      operationId: agentConversationGet
      parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: The conversation and its message turns.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Get a conversation with its turns
      tags:
      - Agent
    patch:
      operationId: agentConversationRename
      parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                title:
                  maxLength: 120
                  type: string
              required:
              - title
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: Renamed.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Rename a conversation
      tags:
      - Agent
  /public/agent/history:
    get:
      operationId: agentHistory
      parameters:
      - in: query
        name: limit
        schema:
          default: 20
          maximum: 100
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: Recent runs.
      summary: List recent agent runs
      tags:
      - Agent
  /public/agent/jobs/{jobId}:
    delete:
      operationId: agentCancel
      parameters:
      - $ref: '#/components/parameters/JobIdParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  job_id:
                    format: uuid
                    type: string
                  ok:
                    example: true
                    type: boolean
                  status:
                    example: cancelled
                    type: string
                type: object
          description: Cancellation accepted.
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: Job queue unavailable.
      summary: Cancel an in-flight agent run
      tags:
      - Agent
    get:
      description: 'Returns the run''s current `status` (queued/running/paused_approval/

        complete/error/cancelled), a `done` boolean, its `result` payload once

        finished, and any `error`. Use this to recover the outcome if the SSE

        stream (`/jobs/{jobId}/stream`) was dropped. Scoped to the job''s owner.'
      operationId: agentJobStatus
      parameters:
      - $ref: '#/components/parameters/JobIdParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  done:
                    type: boolean
                  error:
                    type: string
                  finished_at:
                    format: date-time
                    type: string
                  job_id:
                    format: uuid
                    type: string
                  paused_at_step:
                    type: integer
                  result:
                    description: Accumulated step results (present when finished).
                    type: object
                  status:
                    example: complete
                    type: string
                type: object
          description: Current job status.
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Poll an agent run's status and result
      tags:
      - Agent
  /public/agent/jobs/{jobId}/stream:
    get:
      description: 'Server-Sent Events stream. Each event is a JobEvent JSON object

        (see schema). The stream sends `started` first, zero-or-more

        `token` / `tool_call` / `tool_result` / `progress` events, then

        either `complete` or `error`, then closes.'
      operationId: agentStream
      parameters:
      - $ref: '#/components/parameters/JobIdParam'
      responses:
        '200':
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/JobEvent'
          description: SSE stream — see JobEvent schema.
      summary: Subscribe to live SSE events for an agent run
      tags:
      - Agent
  /public/agent/run:
    post:
      description: 'Submits a prompt to the orchestrator. The agent plans steps,

        calls tools from the registry, and returns the final result.

        Set `stream: true` and consume the SSE stream at

        `/public/agent/jobs/{jobId}/stream` for live tokens + tool calls.'
      operationId: agentRun
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRunRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: Agent run completed.
          headers:
            Idempotency-Replayed:
              $ref: '#/components/headers/IdempotencyReplayed'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          description: Agent gave up after max_iterations (agent_max_iterations).
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
      summary: Run the AI agent orchestrator
      tags:
      - Agent
  /public/agent/run/async:
    post:
      description: 'Same request body and paid gates as `/public/agent/run`, but returns

        `{job_id, session_id, conversation_id, status}` immediately instead of

        blocking. Consume live progress at

        `/public/agent/jobs/{jobId}/stream`; cancel via

        `DELETE /public/agent/jobs/{jobId}`. Cost is debited against the API

        key''s monthly ledger when the run finishes (same amounts as the sync

        route).'
      operationId: agentRunAsync
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRunRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: Run accepted and started; stream for progress.
          headers:
            Idempotency-Replayed:
              $ref: '#/components/headers/IdempotencyReplayed'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: conversation_id not found or not owned by this account.
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
      summary: Run the AI agent asynchronously
      tags:
      - Agent
components:
  responses:
    Conflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: 'Idempotency-Key collision — same key with a different body, or

        a concurrent in-flight request with the same key.

        '
    TooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: Sliding 1-hour rate limit exceeded.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Limit:
          $ref: '#/components/headers/XRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/XRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: Auth failed (missing/malformed/invalid/expired/inactive key).
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestId'
    PaymentRequired:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: Monthly USD cost cap reached for this key (quota_cost_exceeded). Phase 3 / M3.
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: Resource not found.
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: API key lacks required scope (auth_scope_missing).
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: Request validation failed.
    InternalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: Server error. NOT cached by Idempotency-Key — safe to retry.
  schemas:
    ErrorBody:
      additionalProperties: true
      description: 'Additional fields per code (validation errors, retry_after, hints)

        appear at this level. additionalProperties: true is intentional.

        '
      properties:
        code:
          description: 'Stable canonical code from the taxonomy. Branch on this, not

            on `message`. Full list at /api/errors.

            '
          enum:
          - auth_missing_header
          - auth_malformed_header
          - auth_invalid_key
          - auth_expired_key
          - auth_inactive_key
          - auth_scope_missing
          - quota_calls_exceeded
          - quota_cost_exceeded
          - quota_storage_exceeded
          - quota_agent_runs_exceeded
          - credit_exhausted
          - tool_not_found
          - tool_input_invalid
          - tool_file_too_large
          - tool_file_not_found
          - tool_unsupported
          - tool_timeout
          - tool_internal
          - idempotency_key_in_use
          - agent_max_iterations
          - agent_unauthorized_tool
          - agent_invalid_plan
          - workflow_not_found
          - workflow_invalid
          - bad_request
          - forbidden
          - not_found
          - conflict
          - internal_error
          - service_unavailable
          type: string
        doc_url:
          format: uri
          type: string
        message:
          type: string
        request_id:
          format: uuid
          type: string
      required:
      - code
      - message
      - doc_url
      type: object
    Envelope:
      properties:
        data:
          description: Handler payload on success; null on error.
        error:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ErrorBody'
        meta:
          $ref: '#/components/schemas/EnvelopeMeta'
        request_id:
          format: uuid
          type: string
        success:
          type: boolean
      required:
      - success
      - request_id
      - meta
      type: object
    EnvelopeMeta:
      properties:
        rate_limit:
          properties:
            limit:
              type: integer
            remaining:
              type: integer
            reset:
              description: Unix seconds
              type: integer
          type: object
        timestamp:
          format: date-time
          type: string
        version:
          example: '1.0'
          type: string
      required:
      - timestamp
      - version
      type: object
    AgentRunRequest:
      properties:
        conversation_id:
          description: Resume a saved conversation thread (see /public/agent/conversations). Omit to start a new one — the response returns its id.
          format: uuid
          type: string
        file_ids:
          description: File IDs to attach (from POST /public/files)
          items:
            type: string
          type: array
        message:
          description: The task/prompt for the agent to run
          type: string
      required:
      - message
      type: object
    JobEvent:
      additionalProperties: true
      description: 'IMPORTANT — additionalProperties is true intentionally. M4 / future

        phases add new fields without breaking SDK consumers. The named

        cost_usd_so_far / tokens_in / tokens_out / model fields above were

        promoted from additional properties in Phase 2 of SWAGGER_ON_STEROIDS.

        '
      properties:
        cost_usd_so_far:
          description: 'Running total of LLM + per-call costs for this job. Updates

            mid-orchestration so SDK consumers can show spend live.

            '
          example: 0.0341
          format: double
          type: number
        job_id:
          format: uuid
          type: string
        message:
          type: string
        model:
          description: LLM model the current step is using (provider-qualified).
          example: grok-4-fast-non-reasoning
          type: string
        schema_version:
          default: 1
          description: 'Bumped when the event shape changes incompatibly. M3 added

            cost_usd_so_far / tokens_in / tokens_out / model fields without

            bumping schema_version, relying on additionalProperties: true.

            '
          type: integer
        tokens_in:
          description: Input tokens consumed so far.
          type: integer
        tokens_out:
          description: Output tokens generated so far.
          type: integer
        type:
          enum:
          - started
          - progress
          - complete
          - error
          - tool_call
          - tool_result
          - token
          - cost
          type: string
      required:
      - job_id
      - type
      - schema_version
      type: object
  headers:
    IdempotencyReplayed:
      description: Present and `true` when this response is a cached replay.
      schema:
        enum:
        - 'true'
        type: string
    XRequestId:
      description: Unique server-assigned ID for this request, also echoed in `error.request_id`.
      schema:
        format: uuid
        type: string
    XRateLimitReset:
      description: 'Unix timestamp (seconds) when the OLDEST in-window request rolls

        out. Note: this is a rolling timestamp post-K5; pre-K5 it was the

        top of the next clock hour. SDK consumers must NOT cache.

        '
      schema:
        type: integer
    RetryAfter:
      description: Seconds to wait before retrying after 429.
      schema:
        minimum: 1
        type: integer
    XRateLimitLimit:
      description: Max requests allowed in the current sliding 1-hour window.
      schema:
        type: integer
    XRateLimitRemaining:
      description: Requests remaining in the current sliding 1-hour window.
      schema:
        type: integer
  parameters:
    IdempotencyKey:
      description: Opaque client-chosen string ≤255 chars. Identical key + body replays cached response within 24h.
      in: header
      name: Idempotency-Key
      required: false
      schema:
        maxLength: 255
        minLength: 1
        type: string
    JobIdParam:
      in: path
      name: jobId
      required: true
      schema:
        format: uuid
        type: string
  securitySchemes:
    BearerAuth:
      bearerFormat: API Key
      description: 'Bearer token = your API key, prefixed `je_live_sk_`.

        Example: `Authorization: Bearer je_live_sk_abc123...`

        '
      scheme: bearer
      type: http