Hypotize wordmark
Start free

Developers · REST API

The Hypotize REST API

Hypotize is the agent-native Growth OS for growth, product and marketing teams: idea backlog, experiment tracker and learning library in one place. The REST API opens the same experiment record to your automations and scripts.

Read projects, experiments and learnings, add ideas, move tests through the pipeline and record outcomes from n8n, Make, Zapier, Pipedream or your own code. Every write follows the rules of the app: no skipped stages, no test closed without a measured result and a written learning.

Quick start

From API key to your projects in one call

  1. 1. Create an API key. In Hypotize, open Settings, API keys. Choose Read only to read, or Read and write to also create and update. You see the key once: store it in a secret manager.
  2. 2. List your projects. Every other call needs a project ID from this list.
    curl https://api.hypotize.ai/v1/projects \
  -H "Authorization: Bearer $HYPOTIZE_API_KEY"
  3. 3. Add an idea. Needs a Read and write key and the editor or owner role in the project.
    curl -X POST https://api.hypotize.ai/v1/projects/$PROJECT_ID/ideas \
  -H "Authorization: Bearer $HYPOTIZE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idea-2026-11-05-pricing-page" \
  -d '{"title": "Annual plan toggle on the pricing page", "short_idea": "Show the annual price by default", "funnel": "Revenue"}'

Base URL: https://api.hypotize.ai/v1. The OpenAPI 3.1 document describes every endpoint, parameter and field: https://api.hypotize.ai/v1/openapi.json. Import it into Postman, an HTTP node or a code generator.

Endpoints

What you can read and write

An idea is an experiment in the Idea status: the ID returned when you add an idea works with every experiment endpoint.

GET /projects

Projects you can access, with your role

Key: Read only or Read and write

GET /projects/{project_id}

One project with its framework and settings

Key: Read only or Read and write

GET /projects/{project_id}/experiments

Ideas and tests, newest updates at the top

Key: Read only or Read and write

GET /experiments/{experiment_id}

One experiment with scores, outcome and comments

Key: Read only or Read and write

GET /projects/{project_id}/learnings

Results and learnings of closed tests

Key: Read only or Read and write

POST /projects/{project_id}/ideas

Add an idea to the backlog

Key: Read and write

POST /projects/{project_id}/experiments/import

Import up to 50 experiments at any stage

Key: Read and write

PATCH /experiments/{experiment_id}

Change hypothesis, metrics, dates and other fields

Key: Read and write

POST /experiments/{experiment_id}/transition

Move a test to another pipeline stage

Key: Read and write

POST /experiments/{experiment_id}/outcome

Record the result and the learning, and close the test

Key: Read and write

POST /experiments/{experiment_id}/comments

Add a dated comment

Key: Read and write

Safe writes

Retries, conflicts and polling

Idempotency-Key

Send an Idempotency-Key header on every write. A retry with the same key and body within 24 hours returns the original response, with the header Idempotent-Replayed: true, and writes nothing new. The same key with a different body returns 409.

expected_updated_at

Updates, stage moves and outcomes take the experiment's current updated_at. If someone changed the experiment in the meantime, the call returns 409 STALE_EXPERIMENT: read it again and retry.

Pagination

Lists return items and next_cursor. Pass next_cursor as cursor to get the next page, until it is null. limit goes up to 100.

Polling triggers

For new or changed experiments, pass updated_after with the time of your last poll and dedupe on id plus updated_at. For new learnings, read the newest page and dedupe on experiment_id plus updated_at.

Errors and limits

Real status codes, one error shape

Every error has a code and a message. Some add fields that help you fix the call, such as the roles a write needs or the import row that failed.

{
  "error": {
    "code": "INSUFFICIENT_ROLE",
    "message": "This operation requires the editor or owner role; your role in this project is viewer",
    "current_role": "viewer",
    "required_roles": ["editor", "owner"]
  }
}
400
INVALID_REQUEST, INVALID_JSON, INVALID_CURSOR, or a lifecycle rule such as EXPERIMENT_NOT_READY and OUTCOME_REQUIRED
401
UNAUTHORIZED: the key is missing, wrong, revoked or expired
403
FORBIDDEN: a Read only key tried to write. INSUFFICIENT_ROLE: your project role is too low, with required_roles
404
NOT_FOUND: the project or experiment does not exist, or you cannot see it
409
STALE_EXPERIMENT: someone changed the experiment after you read it. IDEMPOTENCY_KEY_REUSED: same key, different body
429
RATE_LIMITED: wait for the Retry-After seconds and try again

Limits per API key, shared with the MCP server: 300 requests per minute and 500 writes every 5 minutes. An import counts one write per row.

For AI agents

Same record, same rules, over MCP

Claude, ChatGPT, Grok Bot, Cursor and other AI agents connect to the MCP server at https://api.hypotize.ai/mcp with OAuth or the same API key. The MCP server also covers projects, tags, frameworks, votes and action plans, which the REST API does not have yet.

Connect an AI agentOpenAPI document