Mnemom Invites API

Invitee-facing product-invite redemption (MNE-7166, 6/8 of the RG invite-permission-product epic MNE-7089). Accepting a `pinv_…` token grants product access and forwards a server-owned starter grant; the grant amount is admin-only and never surfaced.

GitHub OpenAPI

Operations 3

POST /invites/accept Accept a product invite #
GET /invites/preview Preview a product invite (sign-up vs sign-in routing) #
POST /invites/preview Preview a product invite with the token in the body #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/mnemom-ai:mnemom-ai-invites-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

mnemom-ai-invites-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Mnemom Invites API
  description: Trust infrastructure for AI agents. Transparent alignment verification, behavioral drift detection, and accountability primitives.
  version: 1.0.0
  contact:
    name: Mnemom
    url: https://mnemom.ai
    email: support@mnemom.ai
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.mnemom.ai/v1
  description: Production
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: Invites
  description: Invitee-facing product-invite redemption (MNE-7166, 6/8 of the RG invite-permission-product epic MNE-7089). Accepting a `pinv_…` token grants product access and forwards a server-owned starter grant; the grant amount is admin-only and never surfaced.
paths:
  /invites/accept:
    post:
      operationId: acceptProductInvite
      summary: Accept a product invite
      description: 'RG M1 invite flow (MNE-7166). Redeems an opaque `pinv_…` invite token: validates the token, marks the `product_invite` `accepted` exactly-once, grants the invitee access to the invited product(s), and tops the account''s µ balance up to the invite''s per-product entitlement (never a sum, never a debit; computed server-side at accept time) via billing. Invitee-facing and authenticated — a user invite requires the caller to be that user (403 `invite_account_mismatch` otherwise); an email-bound invite requires the caller''s account email (resolved server-side, never from the request) to match the invited address; the emailed token is the proof of inbox possession, so the email need not be confirmed yet (403 `invite_email_mismatch` otherwise; 502 if the identity lookup fails, 503 if no identity provider is configured); an open (QR) invite binds to the first authenticated caller who accepts it, and once claimed behaves like a user invite for that caller (403 `invite_account_mismatch` for anyone else); an org invite requires the caller to be an owner/admin of that org. An open invite minted with `create_workspace` also gives the caller their OWN new org, as its owner, and never adds anyone to an existing org (403 `workspace_invite_invalid` if the stored invite is not an open user invite). Idempotent: a second accept re-asserts access and returns 200 without re-firing the grant. The grant amount is admin-only and never appears in the request or response — the response only reports whether the starter grant `fired` or was `deferred`.'
      tags:
      - Invites
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - token
              properties:
                token:
                  type: string
                  description: The opaque `pinv_…` invite token from the accept link.
      responses:
        '200':
          description: Invite accepted (or already accepted). Product access is granted; the response reports whether the starter grant fired or was deferred. Never carries the grant amount.
          content:
            application/json:
              schema:
                type: object
                required:
                - accepted
                - account_type
                - account_id
                - products
                - onboarding_v2
                properties:
                  accepted:
                    type: boolean
                    description: True once the invite is in the accepted state.
                  already_accepted:
                    type: boolean
                    description: Present and true when the invite was already accepted (idempotent re-accept); the grant is not re-fired.
                  account_type:
                    type: string
                    enum:
                    - user
                    - org
                    description: The account type the product access landed on.
                  account_id:
                    type: string
                    description: The user or org id the product access landed on.
                  products:
                    type: array
                    items:
                      type: string
                    description: The products the invite granted access to.
                  grant:
                    type: string
                    enum:
                    - fired
                    - deferred
                    - pending
                    description: 'Whether the starter grant was settled (`fired`: forwarded to billing, or nothing owed because the products entitle no µ or the account already holds the entitlement), deferred for a later retry/backfill (`deferred`), or still running after this reply (`pending`: a fresh accept answers before the grant is forwarded; an unfinished grant is retried like a deferred one).'
                  open_invite:
                    type: boolean
                    description: Present and true when the invite is an open (email-less QR) invite, on a fresh accept and on a re-accept. A fresh accept of one binds it to the caller and emails the usual invite (with the CLI/MCP steps) to the caller's account email.
                  workspace:
                    type: object
                    required:
                    - org_id
                    - created
                    description: 'Present only for an open invite minted with `create_workspace` (MNE-9738): the caller''s OWN org, of which they are the owner. Always a new org created for this invite, never an existing one. A re-accept reports the same org with `created: false` (finishing it first if an earlier create was interrupted); if that org was tombstoned or is no longer owned by the caller, a NEW org is created instead (`created: true`).'
                    properties:
                      org_id:
                        type: string
                      created:
                        type: boolean
                        description: True when this call created the org.
                  next_path:
                    type: string
                    description: 'Present only with `workspace`: the website path to send the caller to next (`/welcome`).'
                  onboarding_v2:
                    type: boolean
                    description: 'Whether the inviting org has the `org_onboarding_v2` flag on, so the website can pick the onboarding route. Only an org invite has an inviting org; a user invite (including an open QR invite) is always `false`. Fails closed: `false` when the flag cannot be read.'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The invite's state changed concurrently (a competing accept/expire/revoke won the race) — retry. For a `create_workspace` invite, `workspace_state_changed` or `workspace_in_progress` (a concurrent accept is still creating the caller's workspace) — also retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: The invite is expired or revoked and can no longer be accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /invites/preview:
    get:
      operationId: previewProductInvite
      summary: Preview a product invite (sign-up vs sign-in routing)
      description: 'MNE-8335. Unauthenticated and keyed by the secret `pinv_…` token — the same secret that authorises accept. Lets the website send a logged-out invitee to /signup (no account yet) or /login (already has one) before they authenticate. Returns only the effective `status`, the invited `products`, and `needs_account` — true only for a LIVE email-bound user invite whose address has no account yet, or a LIVE open (email-less QR) invite (decided server-side from the invite record; a failed lookup yields `needs_account` false plus `account_state_unknown: true`, so the website shows both sign-up and sign-in). Never returns an email, an id or a grant amount, and there is deliberately no email-keyed variant (MNE-1348 anti-enumeration). A live row past its expiry reports `expired`. Unknown token: 404.'
      tags:
      - Invites
      security: []
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
        description: The opaque `pinv_…` invite token from the accept link.
      responses:
        '200':
          description: Invite preview.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - products
                - needs_account
                properties:
                  status:
                    type: string
                    enum:
                    - live
                    - accepted
                    - expired
                    - revoked
                  products:
                    type: array
                    items:
                      type: string
                  account_state_unknown:
                    type: boolean
                    description: Present (true) only when the account lookup for a live email-bound invite failed, so whether the invited email has an account is unknown. Clients should offer both sign-up and sign-in.
                  needs_account:
                    type: boolean
                    description: True only when the invite is live and its invited email has no account yet.
                  open:
                    type: boolean
                    description: Present (true) only for an open (QR) invite. Lets the website word a used-code refusal as a QR problem and confirm before a signed-in visitor binds the code to themselves.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: previewProductInvitePost
      summary: Preview a product invite with the token in the body
      description: 'Previews a product invite with the secret `pinv_…` token in the JSON body instead of the query string, so it never lands in URLs, access logs, browser history or Referer headers. Same handler, response and public rate limit as `GET /invites/preview`. Prefer this over the GET. A `token` in the query string is ignored. Missing or malformed body: 400. Unknown token: 404.'
      tags:
      - Invites
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - token
              additionalProperties: false
              properties:
                token:
                  type: string
                  description: The opaque `pinv_…` invite token from the accept link.
      responses:
        '200':
          description: Invite preview.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - products
                - needs_account
                properties:
                  status:
                    type: string
                    enum:
                    - live
                    - accepted
                    - expired
                    - revoked
                  products:
                    type: array
                    items:
                      type: string
                  account_state_unknown:
                    type: boolean
                    description: Present (true) only when the account lookup for a live email-bound invite failed, so whether the invited email has an account is unknown. Clients should offer both sign-up and sign-in.
                  needs_account:
                    type: boolean
                    description: True only when the invite is live and its invited email has no account yet.
                  open:
                    type: boolean
                    description: Present (true) only for an open (QR) invite. Lets the website word a used-code refusal as a QR problem and confirm before a signed-in visitor binds the code to themselves.
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/CrossOriginRejected'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: An upstream dependency is currently unavailable. The request was not processed; retry after the cooldown window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadGateway:
      description: An upstream dependency returned an invalid response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
        X-RateLimit-Limit:
          description: Requests permitted per window.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests remaining in the current window (0 on a 429).
          schema:
            type: integer
            minimum: 0
        X-RateLimit-Reset:
          description: Unix epoch seconds at which the current window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    CrossOriginRejected:
      description: Cross-origin write refused (`cross_origin_rejected`). A state-changing request that carries the browser session cookie must come from a first-party origin (`Origin`, or failing that `Referer`) and must not send a form-style body (text/plain, urlencoded, multipart) the operation does not declare. Bearer and API-key callers are never subject to this check.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      description: Canonical error envelope (ADR-API-001 conv 1). `error` is always an object — never a bare string. Every 4xx/5xx response across the API conforms to this shape; the runtime helper is `src/http-errors.ts::buildErrorBody`.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              pattern: ^[a-z][a-z0-9_]*$
              description: 'Stable, machine-matchable failure identifier (lowercase snake_case). Clients may branch on this; the string is part of the contract.


                **Status-class defaults** — emitted when no caller code is supplied (`errorCodeForStatus(status)`): `bad_request` (400), `unauthorized` (401), `forbidden` (403), `not_found` (404), `method_not_allowed` (405), `conflict` (409), `gone` (410), `precondition_failed` (412), `payload_too_large` (413), `unsupported_media_type` (415), `unprocessable_entity` (422), `precondition_required` (428), `rate_limited` (429), `internal_error` (500), `not_implemented` (501), `bad_gateway` (502), `service_unavailable` (503), `gateway_timeout` (504). Fallback `error` for unmapped statuses.


                **Caller-supplied codes** — handlers may pass an explicit `code` for a specific failure class. Examples: `agent_not_found`, `invalid_hash_proof`, `already_linked`, `idempotency_conflict`, `feature_gated`, `schema_validation_failed`, `no_token`, `bad_canonical_payload`.


                **Care-framed sub-resource codes** — the cards-as-primitive surface passes its stable care code-string straight through as `error.code`. Examples: `if_match_absent`, `if_match_stale`, `if_match_malformed`, `primitive_validation_failed`.'
            message:
              type: string
              description: Human-readable, care-framed explanation of the failure.
            details:
              description: 'Optional structured context for the failure (any JSON value: object, array, or primitive). Common shapes: validation findings list, idempotency-conflict diff, `{presented_etag, current_etag}` on a stale `If-Match`, etc. Mirrors the helper''s `details?: unknown`.'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Supabase JWT token in Authorization: Bearer header'
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Mnemom-Api-Key
      description: Mnemom API key (mnm_... format)
    ServiceRole:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Supabase service role bearer JWT. Used by /blog admin operations that talk directly to Supabase. NOT used by /internal/* or /v1/arena/internal/* — those use the custom-header schemes below.
    InternalKeyAuth:
      type: apiKey
      in: header
      name: X-Internal-Key
      description: Internal service-to-service shared secret, timing-safe compared against INTERNAL_API_KEY. Used by /internal/* gateway routes (compose, agents, webhooks emit).
    ServiceKeyAuth:
      type: apiKey
      in: header
      name: X-Service-Key
      description: Service-to-service shared secret, timing-safe compared against MNEMOM_SERVICE_KEY. Used by /v1/arena/internal/*, /v1/on-chain/*, and the /v1/internal/* readers consumed by the reputation cron.
    CoherenceTokenAuth:
      type: http
      scheme: bearer
      description: Per-cell coherence bearer token. Provisioned in 1Password vault `mnemom-coherence` (one item per receiver). Value compared against COHERENCE_<NAME>_SERVICE_TOKEN_EXPECTED. Used by /v1/internal/coherence/* and /v1/internal/governance/dispatch.
    ArenaCandidateTokenAuth:
      type: http
      scheme: bearer
      description: Dedicated arena writer token (ADR-004 §"Arena dedicated writer token"). Compared against ARENA_RECIPE_CANDIDATE_TOKEN. The token's only capability is writing recipe candidates with writer_identity='arena-bypass' (stamped server-side). Used by POST /v1/internal/recipe-candidates.
    CustomerVoiceTokenAuth:
      type: http
      scheme: bearer
      description: Customer Voice API bearer token. Timing-safe compared against CUSTOMER_VOICE_API_TOKEN. Grants access to all /v1/internal/feedback/* endpoints (MNE-1876). No customer-facing or reporter-read capability.
    CookieAuth:
      type: apiKey
      in: cookie
      name: mnemom_session
      description: 'HttpOnly, Secure, SameSite=Lax cookie issued by /v1/auth/sign-in (or the SSO / email-callback flows). The value is an AES-256-GCM-encrypted blob of {access_token, refresh_token, issued_at, auth_method}. Browser clients include this automatically with `credentials: "include"`.'
    LicenseJwtAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: License JWT (HS256, HMAC-signed with LICENSE_SIGNING_SECRET). Used by self-hosted deployment instances to authenticate `/v1/deployments/heartbeat`. Not interchangeable with the Supabase user JWT.
    AgentAuth:
      type: apiKey
      in: header
      name: X-Mnemom-Agent-Proof
      description: 'Agent possession proof: the full SHA-256 hex digest of `${apiKey}|${agentName}` (or `${apiKey}` for an unnamed singleton agent) — the same `hash_proof` primitive used by POST /v1/agents claim, link-agent, and verify-binding. The server resolves the agent by `agent_hash = proof[:16]`. The agent''s *own* identity (ADR-API-001 third auth class) — distinct from ApiKeyAuth (`X-Mnemom-Api-Key`, which resolves a user/account, not an agent).'