John\'s Essentials Files 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 Files 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: Upload, list, download, and delete files attached to your account
  name: Files
paths:
  /public/files:
    get:
      operationId: listFiles
      parameters:
      - in: query
        name: limit
        schema:
          default: 50
          type: integer
      - in: query
        name: cursor
        schema:
          type: string
      responses:
        '200':
          description: File list.
      summary: List your files
      tags:
      - Files
  /public/files/upload:
    post:
      operationId: uploadFile
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                file:
                  format: binary
                  type: string
              required:
              - file
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    data:
                      $ref: '#/components/schemas/File'
                  type: object
          description: File registered.
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
      summary: Upload a file
      tags:
      - Files
  /public/files/{id}:
    delete:
      operationId: deleteFile
      parameters:
      - $ref: '#/components/parameters/FileIdParam'
      responses:
        '204':
          description: Deleted.
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Delete a file
      tags:
      - Files
  /public/files/{id}/download:
    get:
      operationId: downloadFile
      parameters:
      - $ref: '#/components/parameters/FileIdParam'
      - description: '`inline` asks the browser to show the file in place (for example a

          PDF in an iframe) instead of saving it. `attachment`, the default,

          sends it as a download.

          '
        in: query
        name: disposition
        schema:
          default: attachment
          enum:
          - inline
          - attachment
          type: string
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: Raw file bytes.
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Download a file
      tags:
      - Files
components:
  parameters:
    FileIdParam:
      in: path
      name: id
      required: true
      schema:
        type: string
    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
  responses:
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: Resource not found.
    PayloadTooLarge:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: Uploaded file exceeds the per-tier size limit.
  schemas:
    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
    File:
      properties:
        created_at:
          format: date-time
          type: string
        id:
          type: string
        mime_type:
          type: string
        name:
          type: string
        size:
          type: integer
      required:
      - id
      - name
      - size
      - created_at
      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
    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
  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