Minds v1 API Endpoint Catalog

This catalog lists the complete customer-facing v1 route surface. Use it with the live OpenAPI 3.1 document for schemas and the agent integration guide for safe orchestration patterns.

Conventions

• Apex base URL: https://getminds.ai/api/v1
• API-subdomain base URL: https://api.getminds.ai/v1
• Authentication: Authorization: Bearer minds_…
• JSON requests: Content-Type: application/json
• Most JSON responses use { "data": ... }; validation and access failures use the shared error envelope documented under Errors & Limits.
• {id}, {mindId}, {studyId}, and similar tokens are path parameters, not literal strings.
• DELETE operations are destructive. Confirm the exact resource identifiers before calling them.
• MCP mappings identify the equivalent capability. An MCP tool may compose more than one v1 request or expose several routes through an action parameter.

Meta, identity, and credentials

MCP sessions cannot mint, rotate, or revoke their own bearer credentials. Manage credentials only through authenticated account settings or the REST endpoints above.

Minds

The historical API resource name for a Mind is spark.

Batch deletion accepts:

{
  "mindIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

The response reports deleted, notFound, and failed IDs independently so one cleanup failure does not conceal the rest of the batch.

Mind knowledge

For agent-originated files, pass a public, short-lived signed, or Minds workspace-upload URL rather than base64 content:

{
  "file": {
    "name": "research-brief.pdf",
    "url": "https://signed.example/research-brief.pdf",
    "type": "application/pdf"
  },
  "description": "Primary customer research brief",
  "regeneratePrompt": true
}

Remote retrieval is SSRF-guarded, limited to 50 MB, and time-bounded. Multipart and URL-referenced files enter the same storage and processing queue.

Canonical product resources are Audiences and Studies. The former /api/v1/groups and /api/v1/panels paths remain callable during the compatibility window, but return Deprecation: true and a Link header pointing to the canonical successor. New integrations should not use the legacy paths or names.

Audiences and grounding

Audiences and Studies are private by default. Set isLinkSharingEnabled: true only when the user explicitly requests a public link; doing so can make persisted grounding and attached research context readable through the shared surface.

Audience member additions require a JSON object within 64 KiB, including ignored fields. A mindIds array accepts at most 1,000 entries before deduplication; split larger additions into separate requests. Invalid JSON or excess IDs returns 400; excess body bytes returns 413. Legacy Group URLs enforce the same limits. Audience member additions use mindId or mindIds (mindId takes precedence). UUID case variants count as one ID; data.added includes IDs that were already members. The owner-only write rechecks ownership, Mind access, and remaining capacity in one transaction. Concurrent additions cannot both consume the last slot; a rejected batch adds nothing. Responses are private and non-cacheable, with generic 500 errors for unexpected storage or plan-resolution failures.

Member removal is owner-only and atomically deletes the Audience membership plus that Mind’s subgroup assignments on the same Audience. It preserves the Mind itself and other Audiences. Ownership is rechecked within the write; transaction failure preserves both membership and assignments. Success is an empty 204, even when membership was already absent. Missing/unowned Audiences return 404, unexpected storage failures a generic 500; responses are private and non-cacheable.

Audience validation

Audience Validation checks an Audience against real, published surveys and scores how close its Minds' answers are to the published answers. See Validate an Audience against real surveys for request options, results, costs, and failure codes.

Audience Formations

A Formation is a persisted segmentation of one Audience into defined subgroups.

Formation listing is paginated: limit defaults to 100 (maximum 100), offset defaults to 0, and pagination returns total, limit, offset, hasMore and nextOffset. Select auto-dimension winners before counting or paging; timestamp ties use descending IDs. Follow nextOffset until hasMore is false. Each page is internally consistent, while concurrent changes can shift later offsets. Only offset 0 seeds defaults and checks stalled builds. Recovery checks at most 100 pending builds, oldest first; a failed attempt does not stop other selected attempts or prevent the list response. Reopen offset 0 to retry pending work. Both list_formations and manage_formation (action: "list") expose the same page controls.

Successful build completion checks for both missing and newly added Audience members. If the classified snapshot no longer matches, the worker requests a retry without replacing the saved buckets. A short database lock closes the gap between that check and committing the ready state. Empty or degenerate failure decisions also require an unchanged population; a cap failure requires the current member count to remain above the limit. Queued execution errors preserve building until the last configured attempt; exhaustion records a sanitized failure. The synchronous no-Redis path has one attempt and settles as failed on execution errors.

Incremental classification commits a replacement assignment set for one Mind and one Formation; it does not accumulate the results of earlier classifications. Provider outages leave the saved set untouched. Numeric-balanced dimensions accept additional members only through explicit recomputation.

Formation detail responses are private and non-cacheable. Only documented fields are exposed, and failure reasons are sanitized. Invalid legacy proposals become {}, malformed building progress becomes null, and ready builds always return progress: null. Invalid persisted detail metadata and unexpected storage errors return a generic 500. Recompute can retain the previous completed subgroups until replacement succeeds, so check status before treating assignments as final.

Formation creation accepts at most 64 KiB of JSON and returns private, non-cacheable responses. Its hypothesis must have non-empty text and 2–15 subgroups with unique trimmed IDs and labels; unanswered, __unanswered, and __other are reserved IDs. Invalid input returns 400, oversized requests 413, and unexpected storage errors a generic 500. name is optional but must be a string. A user-created split requires two populated primary buckets to become ready. Deletion before acknowledgement returns 404.

Formation delete and recompute responses are private (Cache-Control: private, no-store), including refusals. Unexpected database or queue failures return a generic 500; a missing or non-mutable Formation remains 404. After an uncertain recompute response, inspect the Formation’s status before retrying.

Preview request contract: body ≤64 KiB; optional userInput ≤2000 trimmed characters; optional priorHypothesis matching the creation schema (null also means no prior proposal). Empty requests use the default prompt. Input refusals are 400 or 413; storage errors fail before streaming with a generic 500. Responses prohibit caching. Generated output is validated and stripped to creation fields, including its serialized size. Generation errors use HTTP 500 for JSON and error → done events for an established NDJSON stream. Client disconnects and stream cancellation propagate an abort signal to the model executor.

The preview endpoint content-negotiates. Use Accept: application/x-ndjson for incremental browser progress or Accept: application/json for a single agent-friendly hypothesis. Both representations use the same generator. Negotiation honors q weights, specific ranges, wildcards and UTF-8 media parameters; explicit rejection cannot be overridden by a less-specific wildcard. No header selects NDJSON. A request that accepts neither available representation receives a private 406 before the model is called.

Studies, analytics, and exports

Composite creation through audienceConfigs is atomic: if any inline Audience fails, the operation rolls back the Study and Audiences created by that request. The legacy groupIds and groupConfigs request fields remain accepted on deprecated routes; canonical Study routes use audienceIds and audienceConfigs and return studyMode: "study" with an audiences collection.

Guided Studies and durable runs

For any broader objective or more than one question, plan and execute one cohesive multi-question block. Related questions should be organized into named modules or sections and run together; reserve the direct ask endpoint for a genuinely standalone question.

Creating a plan does not start research. Start only after the user explicitly confirms the exact returned revision. executable: false means a represented method is informational or planned, not runnable.

MCP presentation tools read the same owned state without starting new research. render_audience_review reads operation progress for one Audience or a batch. render_study_plan reads the saved draft through the research-plan service and rejects a stale revision. render_study_results requires one completed question or run with complete response coverage; queued, running, partial and failed results are refused. Poll the existing operation or run first, then show one final widget. Routed not_asked items are settled without fabricated responses, preserving the original questionnaire count and wording. See the MCP tool schemas and review flow.

Study templates

Template responses are private and non-cacheable. Save and update accept JSON bodies up to 1 MiB; use accepts up to 4 KiB. Oversized requests return 413, while malformed JSON or invalid configuration returns 400. The configuration itself is limited to 512 KiB. Expected ownership, revision and file refusals retain their documented statuses; unexpected storage/provider failures return a generic 500.

Durable Study drafts

These endpoints persist the same resumable planner state used by the first-party Study sidebar.

Draft responses use Cache-Control: private, no-store. Creation accepts JSON requests up to 1 MiB; update accepts up to 2 MiB so it can carry both an edited checkpoint and its base. Each versioned payload, including checkpointBase.payload, has a separate 512 KiB limit. Consume requests are limited to 4 KiB. Malformed JSON or invalid fields return 400, oversized input returns 413, and unexpected storage failures return a generic 500. A changed snapshot increments the revision and returns the snapshot written by that update, even if another writer immediately saves a newer revision. An identical save, including acknowledgement of a new checkpointId, preserves its revision and updatedAt.

POST /api/v1/study-drafts accepts idempotencyKey: an optional string whose trimmed length is 1–200 characters. A matching key resolves to that caller’s previously saved draft, so a retry does not apply a replacement payload. Clients that omit this field have no key-based protection against duplicate creation. To edit an existing draft, send PATCH /api/v1/study-drafts/{id} with its latest expectedRevision in the JSON body; identify the draft in the URL rather than sending the MCP-only draftId argument.

For strict optimistic concurrency, send the exact expectedRevision returned by the last read and omit checkpointBase. A stale changed snapshot returns 409; replaying a snapshot that already matches the saved state succeeds.

For concurrent editors or an offline checkpoint queue, send these optional fields on the same PATCH request (or save_study_draft call):

With checkpointBase, the server reconciles changes to independent object fields against the latest saved state. Arrays and strings are whole values. Competing changes to the same field follow commit order; displaced alternatives are retained privately and are not included in draft responses. A repeated checkpointId acknowledges the existing operation and cannot reapply its old snapshot over later edits. Preserve authored save order when replaying a client queue; a network retry does not authorize replacing the original base with a newer read. Use the returned revision for the next new edit.

Consuming an already consumed draft returns its existing tombstone unchanged, including its linked Study. A late base-aware checkpoint is retained privately and acknowledges the consumed draft without reopening it or changing the accepted Study. Consume closes planning state; it does not start or verify research.

Stateful chats

For a one-off Mind request without server-managed history, use the stateless completion endpoint instead.

Choosing the next reference

• Request and response examples: Minds, Audiences, Studies, Knowledge, and Chat
• Authentication and key rotation: Authentication
• Errors, plan limits, and retry policy: Errors & Limits
• Autonomous integrations: API guide for agents
• Tool-native integrations: MCP tools reference

Stripe billing for agents

ACP REST resources use the discovery document's api_base_url and API version 2026-04-17:

Creation requires line_items: [{ id: "price_…" }], currency and capabilities: {}. Optional metadata holds billingCountry, Team quantity and subscription legalAcceptance. The API-Version header may be omitted; if supplied it must match. All POST actions require Idempotency-Key. Buyer interaction happens at the returned continue_url; the adapter reports Stripe's state rather than collecting card details.

The OpenAPI payment offers describe dynamic invoice pricing with amount: null. The runtime challenge supplies the quote. Consult the agent integration guide for authentication headers and uncertain-payment handling.

Custom credit checkout fields

The credit branch of /api/v1/billing/checkout accepts an optional amountMinor budget. When omitted, priceId identifies an unchanged preset or a reusable purchased pack.

The server determines response units and the Stripe Price; callers cannot provide their own unit rate or granted balance. Checkout creation returns the usual hosted URL and session ID without granting access.