John\'s Essentials Memory 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 Memory 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: Per-user persistent memory anchors and search
  name: Memory
paths:
  /public/memory/anchors:
    get:
      operationId: listMemoryAnchors
      responses:
        '200':
          description: Anchor list.
      summary: List memory anchors
      tags:
      - Memory
    post:
      operationId: createMemoryAnchor
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                text:
                  type: string
              required:
              - text
              type: object
        required: true
      responses:
        '201':
          description: Anchor created.
      summary: Create a memory anchor
      tags:
      - Memory
  /public/memory/clear:
    delete:
      operationId: clearMemory
      responses:
        '204':
          description: Cleared.
      summary: Clear all memory for this user
      tags:
      - Memory
  /public/memory/files:
    get:
      operationId: listMemoryFiles
      parameters:
      - description: Page number, starting at 1. A value below 1 is read as 1.
        in: query
        name: page
        schema:
          default: 1
          minimum: 1
          type: integer
      - description: Files per page. A value above 100 is read as 100.
        in: query
        name: limit
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      - description: Only files carrying exactly this tag.
        in: query
        name: tag
        schema:
          type: string
      responses:
        '200':
          description: Memory file list.
      summary: List files in memory
      tags:
      - Memory
  /public/memory/files/{id}:
    delete:
      operationId: deleteMemoryFile
      parameters:
      - $ref: '#/components/parameters/FileIdParam'
      responses:
        '204':
          description: Deleted.
      summary: Delete a memory file
      tags:
      - Memory
  /public/memory/search:
    get:
      operationId: searchMemory
      parameters:
      - in: query
        name: q
        required: true
        schema:
          type: string
      - in: query
        name: limit
        schema:
          default: 20
          type: integer
      responses:
        '200':
          description: Search results.
      summary: Search memory anchors
      tags:
      - Memory
  /public/memory/usage:
    get:
      operationId: getMemoryUsage
      responses:
        '200':
          description: Usage stats.
      summary: Get memory usage stats
      tags:
      - Memory
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
  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