John\'s Essentials MCP 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 MCP 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: 'Model Context Protocol server. Lets every AI client (Claude Desktop,

    Cursor, ChatGPT, Gemini, n8n) plug in to the full tool catalogue with one paste.

    Speaks JSON-RPC 2.0 over HTTP+SSE (remote) or stdio (local desktop).

    Reuses the same `Authorization: Bearer je_live_sk_…` API key.'
  name: MCP
paths:
  /mcp/health:
    servers:
    - description: Production root
      url: https://api.johnsessentials.com
    - description: Local dev root
      url: http://localhost:3000
    get:
      description: 'Public, no auth. Returns server name, version, and the MCP

        protocol version we speak. AI clients hit this to verify

        reachability before the bearer-authenticated handshake.'
      operationId: getMCPHealth
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPHealth'
          description: MCP server is up.
      security: []
      summary: MCP server liveness probe
      tags:
      - MCP
  /mcp/messages:
    servers:
    - url: https://api.johnsessentials.com
    - url: http://localhost:3000
    post:
      description: 'Synchronous JSON-RPC 2.0 request. Common methods:


        - `initialize` — handshake. Returns server capabilities.

        - `notifications/initialized` — client signals it''s ready.

        - `tools/list` — list every callable tool (≥30 free; the full catalogue on paid plans).

        - `tools/call` — execute a tool with arguments.

        - `resources/list` — list `memory://files`, `memory://anchors`, `workflows://saved`.

        - `resources/read` — read a resource by URI.

        - `prompts/list` — list the 6 demo prompts.

        - `prompts/get` — render a prompt with arguments.


        See MCP spec 2025-03-26

        for the full method catalog.'
      operationId: postMCPMessage
      parameters:
      - description: 'Session ID from the `initialize` response. Required for every

          method other than `initialize`.

          '
        in: header
        name: Mcp-Session-Id
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            examples:
              tools_call_qr:
                summary: Generate a QR code
                value:
                  id: 2
                  jsonrpc: '2.0'
                  method: tools/call
                  params:
                    arguments:
                      text: https://johnsessentials.com
                    name: generate_qr_code
              tools_list:
                summary: List available tools
                value:
                  id: 1
                  jsonrpc: '2.0'
                  method: tools/list
            schema:
              $ref: '#/components/schemas/JSONRPCRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JSONRPCResponse'
          description: JSON-RPC response.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: MCP JSON-RPC request
      tags:
      - MCP
  /mcp/messages/server-card:
    servers:
    - url: https://api.johnsessentials.com
    - url: http://localhost:3000
    get:
      description: 'The Server Card from SEP-2127 "MCP Server Cards - HTTP Server Discovery":

        one small JSON document that says who operates this MCP server, where

        its endpoint is, which protocol revisions it speaks, and how a client

        authenticates. It is served at the SEP''s reserved location, the

        streamable-HTTP URL plus `/server-card`, and it deliberately lists no

        tools - the specification reserves that for `tools/list`.


        Public, no authentication. Readable from any browser origin. Carries an

        `ETag`; send `If-None-Match` to receive `304 Not Modified`. The same

        bytes are also served at `/.well-known/mcp.json`, `/.well-known/mcp` and

        `/.well-known/mcp/server-card.json`, the paths some directory crawlers

        request by convention. The domain-level index that points here is

        `/.well-known/ai-catalog.json`.


        Every field is rendered from the same values as `/mcp/health` and the

        `server/discover` result, so the three cannot disagree.'
      operationId: getMCPServerCard
      responses:
        '200':
          content:
            application/mcp-server-card+json:
              schema:
                properties:
                  description:
                    maxLength: 100
                    type: string
                  icons:
                    items:
                      type: object
                    type: array
                  name:
                    example: com.johnsessentials/johns-essentials
                    type: string
                  remotes:
                    items:
                      properties:
                        headers:
                          items:
                            type: object
                          type: array
                        supportedProtocolVersions:
                          items:
                            type: string
                          type: array
                        type:
                          enum:
                          - streamable-http
                          type: string
                        url:
                          format: uri
                          type: string
                      type: object
                    type: array
                  title:
                    example: John's Essentials
                    type: string
                  version:
                    example: 1.2.0
                    type: string
                  websiteUrl:
                    format: uri
                    type: string
                required:
                - name
                - title
                - description
                - version
                - websiteUrl
                - remotes
                type: object
          description: The Server Card.
          headers:
            Cache-Control:
              description: public, max-age=3600
              schema:
                type: string
            ETag:
              description: Strong validator over the document bytes.
              schema:
                type: string
        '304':
          description: Not modified (the `If-None-Match` value matched the current `ETag`).
      summary: MCP Server Card (SEP-2127 discovery document)
      tags:
      - MCP
  /mcp/sse:
    servers:
    - url: https://api.johnsessentials.com
    - url: http://localhost:3000
    get:
      description: 'Long-lived `text/event-stream` connection. The server pushes

        JSON-RPC responses + asynchronous notifications down this stream;

        the client posts requests on `/mcp/messages`. Sessions live in

        Redis with a 15-minute TTL, refreshed on every touch.


        Auth: `Authorization: Bearer je_live_sk_…`. Session ID is issued

        on the `initialize` handshake and echoed back in the

        `Mcp-Session-Id` response header — include it on every subsequent

        `/mcp/messages` POST.


        Keep-alive ping every 30 seconds. Reconnect on disconnect; the

        client resumes by re-sending `initialize`.


        **⚠ "Try it" caveat:** This is an SSE endpoint. Scalar''s in-page

        request runner is built for one-shot request/response cycles,

        not long-lived streams — clicking Try it will either hang or

        dump raw event bytes. Test against this surface with an actual

        MCP client (Claude Desktop, Cursor, the `@modelcontextprotocol/inspector`

        CLI), or follow recipe #5: Connect Claude Desktop.'
      operationId: openMCPStream
      responses:
        '200':
          content:
            text/event-stream:
              schema:
                description: 'Each event frame is `data: <JSON-RPC envelope>\n\n`.

                  The envelope shape is JSONRPCResponse for responses to

                  prior `/mcp/messages` posts, or JSONRPCRequest for

                  server-originated notifications.

                  '
                type: string
          description: SSE stream opened.
          headers:
            Mcp-Session-Id:
              description: Opaque session ID. Echo on subsequent `/mcp/messages` POSTs.
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      summary: MCP server-sent-events stream
      tags:
      - MCP
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
    RetryAfter:
      description: Seconds to wait before retrying after 429.
      schema:
        minimum: 1
        type: integer
    XRequestId:
      description: Unique server-assigned ID for this request, also echoed in `error.request_id`.
      schema:
        format: uuid
        type: string
    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:
    MCPHealth:
      properties:
        protocol_version:
          example: '2025-03-26'
          type: string
        server_name:
          example: john's essentials
          type: string
        server_version:
          example: 1.0.0
          type: string
        status:
          enum:
          - ok
          - degraded
          - down
          type: string
      required:
      - status
      - protocol_version
      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
    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
    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
    JSONRPCRequest:
      properties:
        id:
          description: 'Request ID. Omit for notifications (the server won''t reply).

            '
          oneOf:
          - type: string
          - type: integer
          - type: 'null'
        jsonrpc:
          enum:
          - '2.0'
          type: string
        method:
          description: 'One of: `initialize`, `notifications/initialized`,

            `tools/list`, `tools/call`, `resources/list`, `resources/read`,

            `prompts/list`, `prompts/get`, `ping`.

            '
          type: string
        params:
          description: Method-specific parameters.
          type: object
      required:
      - jsonrpc
      - method
      type: object
    JSONRPCResponse:
      properties:
        error:
          $ref: '#/components/schemas/JSONRPCError'
        id:
          oneOf:
          - type: string
          - type: integer
          - type: 'null'
        jsonrpc:
          enum:
          - '2.0'
          type: string
        result:
          description: Present on success.
      required:
      - jsonrpc
      - id
      type: object
    JSONRPCError:
      properties:
        code:
          description: 'Standard JSON-RPC error codes (-32700 parse error, -32600

            invalid request, -32601 method not found, -32602 invalid

            params, -32603 internal error). MCP additionally uses

            -32001 (CodeNotImplemented), -32002 (lifecycle not ready).

            '
          type: integer
        data:
          description: Optional extra context.
        message:
          type: string
      required:
      - code
      - message
      type: object
  responses:
    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.
    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'
  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