Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.manticscore.com/llms.txt

Use this file to discover all available pages before exploring further.

The Products API is the typed surface iOS uses for card-first idea capture and review. POST /ideas returns a ProductCard in 3-5 seconds after a fast interpretation pass — the full research pipeline continues asynchronously. GET /products/{card_id} returns the ProductDetail payload including the live state, checkpoints, the synthesized artifact, and the top-20 evidence rows with provenance metadata so clients can render source links and freshness badges next to claims.
These endpoints coexist with the legacy POST /research and GET /research/{id}/status flow described in the Research API. The card-first endpoints return strongly typed shapes; the legacy endpoints remain for backward compatibility.

​
Create an idea

Submits a raw idea, runs a fast interpretation cascade (Sonnet, ~3-5s), and returns a ProductCard immediately. Full research is dispatched in the background. Every card returned from this endpoint is guaranteed to have a non-null project_id — the server auto-bridges a project row in the same transaction, and falls back through a defense-in-depth path inside the card-creation chokepoint if the primary bridge fails. Use project_id directly to navigate via GET /projects/{id}. The call is idempotent per user on the semantic content of the idea: re-submitting the same idea reuses the existing project rather than creating a duplicate. If both bridge paths fail, the request fails loudly with 500 BRIDGE_INVARIANT_VIOLATED rather than returning a card the client can’t navigate to. See Errors for the response shape. Rate limit: 20 requests per minute.
​
idea
string
required
The product idea or question. Between 4 and 8,000 characters.
curl -X POST https://api.manticscore.com/ideas \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"idea": "AI expense tracker for freelancers"}'
202 response
{
  "id": "f2a8c1e9-...",
  "research_job_id": "7c3d1e9a-...",
  "project_id": "9f4e2a1b-...",
  "title": "AI expense tracker",
  "product_name": "Receipt-to-Deduction",
  "summary": "Mobile-first OCR expense capture with auto-categorization for self-employed users.",
  "category": "fintech",
  "state": "researching",
  "progress_percent": 5,
  "current_checkpoint": "interpret",
  "created_at": "2026-04-26T09:00:00Z",
  "updated_at": "2026-04-26T09:00:04Z"
}
Subscribe to research progress through GET /research/{job_id}/events using the returned research_job_id.

​
ProductCard fields

​
id
string
required
Product card UUID.
​
research_job_id
string
required
UUID of the research job dispatched for this card. Use it to subscribe to streaming events.
​
project_id
string
UUID of the project row linked to the card. Use it to fetch the project via GET /projects/{id}.Cards returned from POST /ideas always have a non-null project_id — the server fails the request with 500 BRIDGE_INVARIANT_VIOLATED rather than ship a card without one.Cards returned from GET /products and GET /products/{id} may rarely be null if they were created before the project bridge shipped. These pre-bridge cards self-heal: the next time the card is accessed through the card-creation chokepoint (for example, when an existing research job is reattached), the server auto-bridges a project and updates the card row in place. As a defensive fallback, clients can render the card via GET /products/{id} while waiting for the heal to propagate.
​
title
string
required
Short title generated from the idea.
​
product_name
string
Suggested product name.
​
summary
string
One-line summary of the idea.
​
category
string
Auto-assigned product category (for example, fintech, devtools).
​
state
string
required
Lifecycle state: researching, completed, or failed.
​
progress_percent
number
Pipeline progress, 0–100.
​
current_checkpoint
string
Key of the most recent pipeline checkpoint (for example, interpret, search, analyze, synthesize).
​
created_at
string
required
ISO 8601 timestamp the card was created.
​
updated_at
string
required
ISO 8601 timestamp the card was last updated.

​
List products

Returns the authenticated user’s product cards, most-recently-updated first. Reading this list automatically records a list_viewed behavioral event server-side — clients don’t need to instrument it. Rate limit: 60 requests per minute.
​
limit
number
default:"20"
Page size. Between 1 and 100.
​
offset
number
default:"0"
Number of rows to skip. Use with limit for pagination.
curl "https://api.manticscore.com/products?limit=20&offset=0" \
  -H "Authorization: Bearer <token>"
Returns a JSON array of ProductCard objects, ordered by updated_at descending.

​
Get a product

Returns the full ProductDetail for a card the authenticated user owns: the card metadata, the original idea interpretation, classification, checkpoints, the synthesized research artifact (when available), and the top-20 evidence rows. Reading the detail records a detail_opened behavioral event server-side. Rate limit: 60 requests per minute.
​
card_id
string
required
Product card UUID.
curl https://api.manticscore.com/products/f2a8c1e9-... \
  -H "Authorization: Bearer <token>"
200 response
{
  "id": "f2a8c1e9-...",
  "card": {
    "id": "f2a8c1e9-...",
    "research_job_id": "7c3d1e9a-...",
    "project_id": "9f4e2a1b-...",
    "title": "AI expense tracker",
    "product_name": "Receipt-to-Deduction",
    "summary": "Mobile-first OCR expense capture with auto-categorization for self-employed users.",
    "category": "fintech",
    "state": "completed",
    "progress_percent": 100,
    "current_checkpoint": "synthesize",
    "created_at": "2026-04-26T09:00:00Z",
    "updated_at": "2026-04-26T09:04:18Z"
  },
  "idea": {
    "raw_input": "AI expense tracker for freelancers",
    "normalized_idea": "AI-powered expense tracking app for self-employed users",
    "target_user": "Independent contractors and freelancers",
    "problem_statement": "Manual expense capture is error-prone and tax-time hostile.",
    "proposed_solution": "OCR + auto-categorization + tax-deductible flagging."
  },
  "classification": {
    "category": "fintech",
    "subcategory": "expense-management",
    "market_type": "smb",
    "confidence": 0.87
  },
  "checkpoints": [
    {
      "id": "...",
      "job_id": "7c3d1e9a-...",
      "key": "interpret",
      "title": "Interpret idea",
      "status": "completed",
      "summary": "Identified target user and problem statement.",
      "started_at": "2026-04-26T09:00:01Z",
      "completed_at": "2026-04-26T09:00:04Z"
    }
  ],
  "artifact": {
    "id": "...",
    "job_id": "7c3d1e9a-...",
    "product_idea": "AI expense tracker for freelancers",
    "product_category": "fintech",
    "product_name": "Receipt-to-Deduction",
    "short_title": "Tax Deduction Tracker",
    "one_line_summary": "OCR receipt capture with deductible flagging.",
    "market": {
      "audience": ["Freelancers", "Gig workers"],
      "use_cases": ["Receipt capture", "Tax deduction tracking"],
      "competitors": [
        {
          "name": "Expensify",
          "description": "Receipt OCR and expense reports.",
          "url": "https://expensify.com",
          "funding": "Series A — $35M",
          "is_incumbent": true
        }
      ],
      "opportunities": ["Self-employed tax-deduction focus"]
    },
    "recommendation": {
      "score": 78,
      "verdict": "promising",
      "rationale": "Underserved freelancer tax-deduction angle within a mature category."
    },
    "ui_sections": []
  },
  "evidence": [
    {
      "id": "ad21c8b7-...",
      "source_kind": "web",
      "source_url": "https://example.com/freelancer-finance-2026",
      "title": "Freelancer financial tooling 2026",
      "snippet": "Forty-two percent of independent contractors miss deductible mileage expenses.",
      "confidence": 0.92,
      "freshness_score": 0.88,
      "fetched_at": "2026-04-26T09:02:11Z"
    }
  ]
}

​
Response fields

​
id
string
required
Product card UUID. Same as card.id.
​
card
object
required
Card metadata. See ProductCard shape returned by POST /ideas above.
​
idea
object
required
Structured interpretation of the user’s raw idea. Includes raw_input, normalized_idea, target_user, problem_statement, and proposed_solution.
​
classification
object
required
Auto-assigned category, subcategory, market_type, and confidence (0-1) for the idea.
​
checkpoints
array
required
Pipeline checkpoints with status and timing. Each checkpoint has id, job_id, key, title, status, summary, started_at, completed_at.
​
artifact
object
The synthesized ResearchArtifact once research has completed. null while research is still running. Contains the market summary, competitors, recommendation, and renderable UI sections.
​
evidence
array
required
Top-20 evidence rows backing the artifact. Sorted by confidence descending, then freshness_score descending, then fetched_at descending. Clients render these as source-link badges next to competitors and market signals.Evidence rows are populated by the live research pipeline as the analyze stage completes — newly-finished cards return their sources alongside the artifact. Empty arrays mean the job hasn’t reached the analyze stage yet (subscribe to research events) or completed with no attributed sources.
StatusMeaning
200Detail returned.
404Product not found, or owned by another user.

​
Record a behavioral event

Records a behavioral event for outcome-based learning. Most events are auto-recorded server-side by GET /products and GET /products/{id} — call this endpoint only for client-driven signals like card swipes, taps, or shares. Rate limit: 120 requests per minute.
​
event
string
required
Event name. Between 1 and 64 characters.Common event names: list_viewed, detail_opened, card_viewed, section_expanded, card_completed, build_started, share_tapped.Sending build_started or share_tapped also reinforces the canonical entities cited in the card’s artifact, surfacing high-converting companies and features earlier in future retrieval. Other event names are recorded but do not feed the outcome loop.
​
card_id
string
Product card UUID, when the event relates to a specific card.
​
job_id
string
Research job UUID, when the event relates to a specific research run.
​
project_id
string
Project UUID, when the event relates to a specific project.
​
payload
object
default:"{}"
Free-form metadata (numbers, strings, nested objects) to attach to the event.
curl -X POST https://api.manticscore.com/products/events \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"event": "card_shared", "card_id": "f2a8c1e9-...", "payload": {"channel": "imessage"}}'
Returns 204 No Content on success.