John\'s Essentials Tools 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 Tools 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: Tool registry and direct tool execution
  name: Tools
paths:
  /public/tools:
    get:
      description: 'Returns the tools currently offered. The three query parameters narrow

        the list and can be combined; each one is applied only when present.'
      operationId: listTools
      parameters:
      - description: 'Only tools in this category. Exact, case-sensitive match against each

          tool''s `category` field, for example `pdf`, `photo`, `media`,

          `convert`, `analyze` or `generate`. A category no tool has returns an

          empty list, not an error.

          '
        in: query
        name: category
        schema:
          example: pdf
          type: string
      - description: 'Only tools whose `tier_required` is exactly this plan: `free`,

          `starter`, `business` or `enterprise` (case-insensitive). It is not

          "everything this plan can use" — `starter` returns the Starter tools

          and leaves out the free ones. The older names `pro` and `premium`

          are read as `starter` and `business`. Any other value is read as

          `free`.

          '
        in: query
        name: tier
        schema:
          example: starter
          type: string
      - description: 'Leave it out (or send anything other than `false`) to list only the

          tools currently offered. Send `false` to include withdrawn tools as

          well; they carry `is_enabled: false`. No value lists withdrawn tools

          on their own.

          '
        in: query
        name: enabled
        schema:
          default: true
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    data:
                      description: The tool registry plus counts (NOT a bare array).
                      properties:
                        category_counts:
                          additionalProperties:
                            type: integer
                          description: Per-category tool counts.
                          type: object
                        tools:
                          items:
                            $ref: '#/components/schemas/Tool'
                          type: array
                        total:
                          description: Number of tools returned after filters.
                          type: integer
                      type: object
                  type: object
          description: Tool list.
      summary: List the full tool registry
      tags:
      - Tools
  /public/tools/{name}:
    get:
      description: 'A withdrawn tool answers 404 by default, the same as it is absent from

        `GET /public/tools`. Send `enabled=false` to fetch its record anyway.'
      operationId: getTool
      parameters:
      - in: path
        name: name
        required: true
        schema:
          type: string
      - description: 'Leave it out (or send anything other than `false`) and a withdrawn

          tool answers 404. Send `false` to receive its record, which carries

          `is_enabled: false`. A tool that is offered is returned either way.

          '
        in: query
        name: enabled
        schema:
          default: true
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
          description: Tool definition.
        '404':
          $ref: '#/components/responses/NotFound'
      summary: Get one tool's definition
      tags:
      - Tools
  /public/tools/{name}/run:
    post:
      description: 'Runs the named tool with the provided JSON params. Schema for

        params varies per tool — fetch it from `/public/tools/{name}`.

        File inputs may be referenced by ID (uploaded via

        `/public/files/upload`) or sent inline as multipart/form-data.'
      operationId: runTool
      parameters:
      - in: path
        name: name
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
          multipart/form-data:
            schema:
              additionalProperties: true
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    data:
                      $ref: '#/components/schemas/ToolRunResult'
                  type: object
            application/octet-stream:
              schema:
                description: Some tools return binary directly.
                format: binary
                type: string
          description: Tool ran successfully.
          headers:
            Idempotency-Replayed:
              $ref: '#/components/headers/IdempotencyReplayed'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '408':
          description: Tool execution timed out (tool_timeout).
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Execute a tool by name
      tags:
      - Tools
components:
  headers:
    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
    IdempotencyReplayed:
      description: Present and `true` when this response is a cached replay.
      schema:
        enum:
        - 'true'
        type: string
    RetryAfter:
      description: Seconds to wait before retrying after 429.
      schema:
        minimum: 1
        type: integer
    XRateLimitRemaining:
      description: Requests remaining in the current sliding 1-hour window.
      schema:
        type: integer
    XRateLimitLimit:
      description: Max requests allowed in the current sliding 1-hour window.
      schema:
        type: integer
  schemas:
    ToolRunResult:
      properties:
        duration_ms:
          type: integer
        file_id:
          type: string
        size:
          type: integer
        url:
          format: uri
          type: string
      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
    Tool:
      properties:
        avg_duration_ms:
          type: integer
        category:
          example: pdf
          type: string
        description:
          type: string
        display_name:
          type: string
        is_enabled:
          type: boolean
        name:
          example: pdf_compress
          type: string
        parameters_schema:
          description: 'JSON Schema for the tool''s input. The schema and its properties may carry additional keys beginning `x-`; those are hints for our own interface, are not part of the API contract, may change without notice, and never affect the value a parameter accepts or returns — ignore them. A property-level `tier_required` is different and is NOT advisory: on some tools sending that property below the named tier is refused with 402. See "Schema extensions" in the introduction.

            '
          type: object
        tier_required:
          enum:
          - free
          - starter
          - business
          - enterprise
          type: string
      required:
      - name
      - description
      - category
      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
  responses:
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: Resource not found.
    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'
    PaymentRequired:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: Monthly USD cost cap reached for this key (quota_cost_exceeded). Phase 3 / M3.
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: Request validation failed.
    PayloadTooLarge:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: Uploaded file exceeds the per-tier size limit.
  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
  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