Aiso API

Authentication

Include your API key in the x-api-key header on every request. You have one key per account. For project-specific calls, also send x-aiso-project-id with the project UUID. Generate a key in the Aiso app . Keys are stored as SHA-256 hashes, so the raw key is shown once on creation and cannot be retrieved again.

curl -X GET "https://app.getaiso.com/api/v1/projects" \
  -H "x-api-key: aiso_abc123..."

curl -X GET "https://app.getaiso.com/api/v1/prompts" \
  -H "x-api-key: aiso_abc123..." \
  -H "x-aiso-project-id: YOUR_PROJECT_UUID"

Rate limits

Default limits are 10 requests per minute and 20 requests per day per API key. Admins can adjust these per user. Every response includes headers you can use to manage retries.

Base URL

https://app.getaiso.com/api/v1

Models and filtering

Aiso tracks two AI models. Use gpt for OpenAI ChatGPT with web search and gemini for Google Gemini with Google Search grounding. Report endpoints accept a flexible query body with dates, pagination, dimensions, filters, and sort order.

{
  "start_date": "2025-09-01",
  "end_date": "2025-10-01",
  "dimensions": ["date"],
  "filters": [
    { "field": "model_id", "operator": "in", "values": ["gpt"] }
  ],
  "order_by": [{ "field": "visibility", "direction": "desc" }],
  "limit": 100
}

Ready-made request bodies for the questions teams ask most.

{ }

{
  "dimensions": ["date"],
  "filters": [
    { "field": "brand_id", "operator": "in", "values": ["Your Brand"] }
  ]
}

{
  "dimensions": ["model_id"]
}

{
  "dimensions": ["week"],
  "start_date": "2025-08-01"
}

{
  "filters": [
    { "field": "model_id", "operator": "in", "values": ["gpt"] }
  ],
  "order_by": [{ "field": "used_count", "direction": "desc" }],
  "limit": 10
}

{
  "filters": [
    { "field": "domain", "operator": "in", "values": ["g2.com"] }
  ],
  "order_by": [{ "field": "citation_count", "direction": "desc" }]
}

Conversation Explorer

Search the conversation dataset with your account API key. Explorer routes do not use x-aiso-project-id. A semantic search that returns at least one conversation costs 1 tool credit, the same credit the Explorer page spends. Searches with no matches are free. Reading transcripts, listing intents, AI filtering, prompt expansion, and search history are free. With 0 credits, search returns 403.

Use the base URL above with each path below. These account-scoped routes use the same x-api-key authentication as the rest of the API.

{
  "query": "best wireless headphones",
  "brand": "Sony",
  "intent": null,
  "first_prompt_contains": null
}

{
  "data": {
    "conversations": [
      {
        "id": 559924,
        "first_prompt": "...",
        "brands": [
          "Sony"
        ],
        "intent": "recommendation"
      }
    ],
    "credits_remaining": 9,
    "credits_charged": 1
  }
}

{
  "data": {
    "intents": [
      "comparison",
      "recommendation"
    ]
  }
}

{
  "data": {
    "id": 12345,
    "first_prompt": "...",
    "conversation": "Human: ...\nAssistant: ..."
  }
}

{
  "conversations": [
    {
      "id": 559924,
      "first_prompt": "Can you recommend headphones?"
    }
  ],
  "instruction": "Product recommendations only",
  "searchQuery": "headphones"
}

{
  "selected_prompts": [
    {
      "id": 1,
      "first_prompt": "Which headphones should I buy?"
    },
    {
      "id": 2,
      "first_prompt": "Best headphones for commuting?"
    },
    {
      "id": 3,
      "first_prompt": "Compare wireless headphones for calls"
    },
    {
      "id": 4,
      "first_prompt": "Headphones with good battery life?"
    },
    {
      "id": 5,
      "first_prompt": "Recommend noise cancelling headphones"
    }
  ],
  "answers": {
    "industry": "Audio",
    "goal": "Find comparison prompts"
  },
  "target_count": 100
}

Connect Claude, Cursor, or any MCP host directly to your Aiso account. The hosted MCP server wraps the v1 API as 19 tools, with no local install.

1. Create an API key

Go to API keys and create a key. Copy it when shown — it cannot be retrieved again.

2. Add to Cursor

Create .cursor/mcp.json in your project (or edit ~/.cursor/mcp.json globally), then restart Cursor or reload MCP from Settings.

{
  "mcpServers": {
    "aiso": {
      "url": "https://app.getaiso.com/api/v1/mcp",
      "headers": {
        "x-api-key": "aiso_your_key_here",
        "x-aiso-project-id": "your_project_uuid"
      }
    }
  }
}

For local dev, use http://localhost:3000/api/v1/mcp instead. Use list_projects to discover project IDs, then set x-aiso-project-id in the headers.

Legacy stdio clients

If your MCP host does not support remote URLs yet, proxy the hosted endpoint with mcp-remote:

{
  "mcpServers": {
    "aiso": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.getaiso.com/api/v1/mcp",
        "--header",
        "x-api-key:aiso_your_key_here",
        "--header",
        "x-aiso-project-id:your_project_uuid"
      ]
    }
  }
}

Project header

GET /projects without a project header lists all your projects. With x-aiso-project-id, it returns one project. All other project-scoped routes require the header, or ?project_id= on GET.

Setup and prompt writes

POST /projects accepts a domain and runs analysis once, so there is no separate analyze endpoint. Setup and prompt management are open to all API key holders. Each project allows one setup write and one prompt write via the API or MCP: further setup updates return 409 once setup exists, and further prompt writes return 409 once prompts exist. The initial POST /projects may include prompts in the same request. Prompt suggestion and generation require stored setup (domain_data) and do not write to the database, so call add_prompts to save.

Visibility reports

Snapshots, brand, domain, and URL reports, and fanout metrics require a completed visibility analysis run for the project. Until then, those tools return 403 with guidance to reach out at getaiso.com for help.

Explorer tools use the same hosted MCP endpoint and API key. They do not need a project header. The same Explorer credit rules apply.

Available MCP tools

Troubleshooting

MCP endpoint: https://app.getaiso.com/api/v1/mcp · Admin usage: /admin/api