---
title: "API Overview"
nav_title: "API Overview"
description: "Authentication, base URLs, and core resources in the Perspective REST API."
tags: ["REST API", "conversation API", "structured data API", "developer integration"]
date: "2026-05-08"
nav_order: 2
nav_display: true
---

# 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](/docs/build/mcp).

## Authentication

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

```http
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.

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

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `workspaceSlug` | string | Yes | Your workspace slug. This is the workspace `uniqueName` used in dashboard URLs. |
| `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:**

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

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

Common HTTP status codes:

| Status | Meaning |
|--------|---------|
| `400` | Bad request -- check the `error` field and, when present, the `details` array for validation issues. |
| `401` | Missing or invalid MCP bearer token. |
| `404` | Workspace not found, or the authenticated user does not have access. |
| `500` | Unexpected server error. Retry after a short delay. |

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](/docs/build/mcp). It exposes those capabilities with workspace access checks and tool-specific validation.