John\'s Essentials Organizations 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 Organizations 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: 'Read-only access to the teams (organizations) your API key''s owner

    belongs to — enumerate your orgs and read the current org''s roster.

    Every response is scoped to the key owner''s memberships, so a key

    can only ever see its own team(s). Mutations (invite, roles,

    transfer) and billing are session-only and are NOT exposed to API

    keys.'
  name: Organizations
paths:
  /public/organizations:
    get:
      description: 'Returns every team the API key''s owner is an active member of, with

        the owner''s role in each and which one is current. Read-only; scoped

        to the key owner — a key never sees teams it doesn''t belong to.'
      operationId: listMyOrganizations
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    data:
                      properties:
                        count:
                          type: integer
                        organizations:
                          items:
                            $ref: '#/components/schemas/OrganizationSummary'
                          type: array
                      type: object
                  type: object
          description: The teams you belong to.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List your organizations
      tags:
      - Organizations
  /public/organizations/members:
    get:
      description: 'Returns the roster of the key owner''s current organization — a

        curated, secret-free projection (id, email, role, status,

        joined_at). Pending invitations appear with their invited email and

        `status: pending`. Read-only; scoped to your own team. Returns an

        empty list if you are not in an organization. Never includes Stripe

        ids or other members'' account internals.'
      operationId: listOrgMembers
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    data:
                      properties:
                        count:
                          type: integer
                        members:
                          items:
                            $ref: '#/components/schemas/OrganizationMemberPublic'
                          type: array
                      type: object
                  type: object
          description: Your team's roster.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List your current team's members
      tags:
      - Organizations
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:
    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
    OrganizationMemberPublic:
      description: A curated, secret-free view of one team member. Never includes Stripe ids or other account internals.
      properties:
        email:
          description: Member's email, or the invited email for a pending seat.
          format: email
          type: string
        id:
          description: Membership id (not the user id).
          format: uuid
          type: string
        joined_at:
          description: When the member accepted; absent while pending.
          format: date-time
          type: string
        role:
          enum:
          - owner
          - admin
          - member
          - viewer
          type: string
        status:
          enum:
          - pending
          - active
          - suspended
          type: string
      required:
      - id
      - email
      - role
      - status
      type: object
    OrganizationSummary:
      description: One organization the API key's owner belongs to.
      properties:
        id:
          format: uuid
          type: string
        is_current:
          description: True for the owner's default/active organization.
          type: boolean
        name:
          example: Northwind Studio
          type: string
        role:
          description: The key owner's role in this org.
          enum:
          - owner
          - admin
          - member
          - viewer
          type: string
        tier:
          description: The org's plan; every active seat inherits this tier.
          enum:
          - free
          - starter
          - business
          - enterprise
          type: string
      required:
      - id
      - name
      - tier
      - role
      - is_current
      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
  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'
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Envelope'
      description: API key lacks required scope (auth_scope_missing).
    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