API Overview

Perspective exposes a focused REST API at /api/v1/ for backend workflows that need to create perspectives or read public embed configuration. For broader automation, including listing perspectives, reading conversations, inviting participants, and managing automations, use the Perspective MCP server.

Authentication#

The create endpoint requires a personal MCP token in the Authorization header:

Authorization: Bearer <your-mcp-token>

Generate a token from the MCP settings page. In the app, open the profile menu at the bottom of the sidebar and choose MCP, or open the workspace switcher, choose Manage workspace, and select MCP. The token identifies your Perspective user, and each request still validates that the user has access to the workspaceSlug in the request body.

OAuth access tokens issued for remote MCP clients are audience-bound to /mcp and are not accepted by the REST create endpoint today. Use OAuth for the MCP endpoint and a personal MCP token for this REST endpoint.

The embed configuration endpoint is public because the Embed SDK calls it from customer websites.

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 during the request to generate an outline from your prompt.

Request body:

Response:

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

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

API-created perspectives start with the same product defaults as dashboard-created perspectives, including default interview auth providers and the default participant thank-you/reminder email settings. You can change those settings afterward in the perspective editor.

Embed Configuration#

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

Returns the public embed configuration for a given perspective. This is the endpoint the Perspective Embed SDK calls internally to load theme colors, allowed channels, the welcome message, avatar information, and saved embed settings.

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

Implementation details:

• The endpoint is unauthenticated and sends CORS headers so browser embeds can call it from any origin.
• Responses are cached for a short period (max-age=300, stale-while-revalidate=600).
• If a perspective cannot be loaded, the endpoint returns a default embed config instead of exposing a lookup error to the browser embed.

Error Handling#

Errors from authenticated REST endpoints follow this shape:

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

Common HTTP status codes:

The public embed config endpoint is intentionally more forgiving: missing or failed lookups return a default configuration so embeds can continue rendering.

Use MCP for Broader Automation#

The REST API is intentionally narrow today. If you need to list or update perspectives, fetch conversation summaries or transcripts, generate preview/embed links, invite participants, manage automations, or inspect connected integrations, use the MCP server. It exposes those capabilities with workspace access checks and tool-specific validation.