LoginSign up

API Overview

Updated: March 30, 2026

Perspective exposes a REST API at /api/v1/ that lets you create conversation agents, retrieve embed configurations, and integrate Perspective into your backend workflows. The API surface is actively growing -- the endpoints below are stable, and more are coming.

Authentication

All API requests require a bearer token in the Authorization header. Tokens are scoped to your workspace.

To generate a token, click your profile in the bottom left corner of Perspective and select MCP. The same token works for both the MCP server and the REST API.

bash
curl https://getperspective.ai/api/v1/perspective/create \  -H "Authorization: Bearer $PERSPECTIVE_TOKEN" \  -H "Content-Type: application/json" \  -d '{ "workspaceSlug": "my-workspace", "userPrompt": "Customer discovery for mobile app" }'

Endpoints

Create a Perspective

POST /api/v1/perspective/create

Creates a new conversation agent (perspective) in your workspace. The design agent runs automatically to generate an interview outline from your prompt.

Request body:

FieldTypeRequiredDescription
workspaceSlugstringYesYour workspace slug (visible in the dashboard URL).
userPromptstringYesA description of what the conversation agent should do.
agentContextstringNoAgent type. If omitted, it is auto-classified from the prompt. Accepted values: research (Interviewer), form (Concierge), survey (Evaluator), advocate (Advocate).

Response:

json
{  "perspectiveId": "abc123",  "workspaceId": "ws_456",  "workspaceName": "My Workspace",  "status": "ready",  "agentGuidance": null,  "fields": ["question_1", "question_2"],  "previewUrl": "https://getperspective.ai/preview/abc123",  "shareUrl": "https://getperspective.ai/i/abc123",  "directUrl": "https://getperspective.ai/i/abc123",  "followUpQuestion": null}

The status field is either "ready" (outline generated, agent deployed) or "needs_input" (the design agent needs clarification -- check followUpQuestion).

Embed Configuration

GET /api/v1/embed/config/:researchId

Returns the embed configuration for a given perspective. This is the endpoint the Perspective Embed SDK calls internally to load interview settings, theme, and metadata.

You generally do not need to call this directly -- the embed script handles it. It is documented here for teams building custom embed integrations.

Error Handling

All errors follow a consistent shape:

json
{  "error": "Outline 123 not found in workspace abc"}

Common HTTP status codes:

StatusMeaning
400Bad request -- check the error field and details array for validation issues.
401Missing or invalid bearer token.
404Workspace or resource not found, or the token does not have access.
500Server error. Retry after a short delay.

Rate Limits

API requests are rate-limited per token. If you exceed the limit, the response returns 429 Too Many Requests with a Retry-After header indicating how long to wait.

What Is Coming

The API surface is expanding. Planned additions include:

  • List and manage outlines -- retrieve, update, and archive existing perspectives.
  • Conversation export -- fetch transcripts, metadata, and trust scores.
  • Invite management -- trigger invites and send reminders programmatically.
  • Highlight pages -- publish and retrieve highlight pages via API.

If you need an endpoint that does not exist yet, the MCP server exposes a broader set of capabilities today and is the fastest way to automate Perspective workflows.