API Overview | Docs | Perspective AI

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.

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:

Field	Type	Required	Description
`workspaceSlug`	string	Yes	Your workspace slug (visible in the dashboard URL).
`userPrompt`	string	Yes	A description of what the conversation agent should do.
`agentContext`	string	No	Agent type. If omitted, it is auto-classified from the prompt. Accepted values: `research` (Interviewer), `form` (Concierge), `survey` (Evaluator), `advocate` (Advocate).

Response:

{
  "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:

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

Common HTTP status codes:

Status	Meaning
`400`	Bad request -- check the `error` field and `details` array for validation issues.
`401`	Missing or invalid bearer token.
`404`	Workspace or resource not found, or the token does not have access.
`500`	Server 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.