> ## Documentation Index > Fetch the complete documentation index at: https://docs.parallellabs.app/llms.txt > Use this file to discover all available pages before exploring further. # List all content research projects for a company. > Each project targets one domain and one ideal customer profile. A company can have many, and opportunities are scoped per project. ## OpenAPI ````yaml https://api.parallellabs.app/docs/openapi.json get /api/v0/research/projects openapi: 3.0.3 info: description: > # Introduction Welcome to the API. This API provides programmatic access to all platform features including AI agents, smart lists, documents, sequences, and media generation. ## Authentication The API supports two types of authentication: 1. **Company API Keys** - Scoped to a specific company 2. **Personal Access Keys** - User-level keys that work across all your companies --- ### Option 1: Company API Key Company API keys are tied to a specific company. Use this when you only need to access one company. **Getting a Company API Key:** 1. Log in to your dashboard 2. Navigate to **Integrations** page 3. Find the **API Keys** section and click **Generate New Key** 4. Copy and securely store your API key (it won't be shown again) **Usage:** Include your API key in the `X-API-Key` header: ```bash curl -X GET "https://api.example.com/api/v0/agents" \ -H "X-API-Key: YOUR_COMPANY_API_KEY" \ -H "Content-Type: application/json" ``` Or use the `Authorization` header (OpenAI-compatible): ```bash curl -X GET "https://api.example.com/api/v0/agents" \ -H "Authorization: Bearer YOUR_COMPANY_API_KEY" \ -H "Content-Type: application/json" ``` --- ### Option 2: Personal Access Key Personal access keys are tied to your user account and can access any company you belong to. Use this when you need to access multiple companies or build integrations that work across companies. **Getting a Personal Access Key:** 1. Log in to your dashboard 2. Click on your avatar/profile icon and go to **Profile** 3. Find the **Personal Access Keys** section 4. Click **Create New Key** 5. Give it a name and optionally set an expiration date 6. Copy and securely store your key (it won't be shown again) **Usage:** Personal access keys start with `pak_` and **require** you to specify which company to access using the `X-Company-ID` header: ```bash curl -X GET "https://api.example.com/api/v0/agents" \ -H "Authorization: Bearer pak_your_personal_access_key" \ -H "X-Company-ID: your_company_id" \ -H "Content-Type: application/json" ``` Or using the `X-API-Key` header: ```bash curl -X GET "https://api.example.com/api/v0/agents" \ -H "X-API-Key: pak_your_personal_access_key" \ -H "X-Company-ID: your_company_id" \ -H "Content-Type: application/json" ``` You can also pass the company ID as a query parameter: ```bash curl -X GET "https://api.example.com/api/v0/agents?companyId=your_company_id" \ -H "Authorization: Bearer pak_your_personal_access_key" \ -H "Content-Type: application/json" ``` **Finding Your Company ID:** Your company ID can be found in the dashboard URL when viewing a company, or via the Settings page. --- ### Which Key Type Should I Use? | Use Case | Recommended Key Type | |----------|---------------------| | Single company integration | Company API Key | | Multi-company dashboard | Personal Access Key | | CI/CD pipelines | Company API Key | | Personal automation scripts | Personal Access Key | | Third-party app integration | Company API Key | --- ## Response Format All responses are returned in JSON format. Successful responses include the requested data: ```json { "id": "abc123", "name": "My Agent", "created": "2024-01-15T10:30:00Z" } ``` Error responses follow a consistent structure: ```json { "error": "Description of what went wrong" } ``` ## HTTP Status Codes | Code | Description | |------|-------------| | 200 | Success | | 201 | Created | | 400 | Bad Request - Invalid parameters | | 401 | Unauthorized - Invalid or missing API key | | 403 | Forbidden - Insufficient permissions | | 404 | Not Found - Resource doesn't exist | | 429 | Too Many Requests - Rate limit exceeded | | 500 | Internal Server Error | ## Pagination List endpoints support pagination using `page` and `pageSize` parameters: ``` GET /api/v0/agents?page=1&pageSize=20 ``` Paginated responses include: - `items`: Array of results - `total`: Total number of items - `pages`: Total number of pages - `hasNext`: Whether more pages exist ## OpenAI Compatibility The Chat API (`/api/v0/chat/completions`) is fully compatible with the OpenAI API specification. --- ## MCP (Model Context Protocol) Integration The platform provides an MCP server that allows AI assistants like Claude Desktop, Cursor, Windsurf, and other MCP-compatible tools to interact with the full platform API. ### What is MCP? Model Context Protocol (MCP) is an open standard that allows AI assistants to securely connect to external tools and data sources. With MCP, your AI assistant can: - Browse and manage your AI agents - Create and monitor outreach sequences - Search your knowledge base documents - Generate AI content, images, audio, and video - Execute browser automation tasks - And access every other platform feature ### MCP Server URL ``` https://api.example.com/api/v0/mcp ``` This endpoint implements the **MCP Streamable HTTP Transport** (JSON-RPC 2.0) and is compatible with `mcp-remote` and other MCP clients. ### Available Tools The MCP server provides 3 tools that give access to the entire platform API: | Tool | Description | |------|-------------| | `platform_list_capabilities` | Browse available API endpoints by category (Agents, Sequences, Lists, Documents, etc.) | | `platform_get_action_details` | Get the full specification for an endpoint including required parameters | | `platform_execute_action` | Execute any API endpoint with automatic authentication | ### Connecting Claude Desktop 1. Open your Claude Desktop configuration file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` 2. Add the MCP server configuration: ```json { "mcpServers": { "platform": { "command": "npx", "args": ["-y", "mcp-remote", "https://api.example.com/api/v0/mcp"], "env": { "API_KEY": "your_api_key_here" } } } } ``` 3. Restart Claude Desktop 4. You can now ask Claude to interact with your platform data, for example: - "List my AI agents" - "Show me my active sequences" - "Create a new email sequence for cold outreach" - "Search my documents for pricing information" ### Connecting Cursor / Windsurf 1. Open Settings and navigate to the MCP section 2. Add a new MCP server with: - **URL**: `https://api.example.com/api/v0/mcp` - **Authentication**: Bearer token with your API key 3. The platform tools will now be available in your AI assistant ### Connecting via mcp-remote (Generic) For any MCP-compatible client, you can use the `mcp-remote` package: ```bash npx mcp-remote https://api.example.com/api/v0/mcp --header "Authorization: Bearer YOUR_API_KEY" ``` ### Authentication for MCP MCP requests use the same authentication as the REST API: **Using Company API Key:** ``` Authorization: Bearer YOUR_COMPANY_API_KEY ``` **Using Personal Access Key:** ``` Authorization: Bearer pak_your_personal_access_key X-Company-ID: your_company_id ``` ### Example MCP Interactions **List available capabilities:** ```json { "name": "platform_list_capabilities", "arguments": { "category": "Sequences" } } ``` **Get action details:** ```json { "name": "platform_get_action_details", "arguments": { "operationId": "post_sequences.create_sequence" } } ``` **Execute an action:** ```json { "name": "platform_execute_action", "arguments": { "operationId": "get_agents.list_agents" } } ``` ### MCP Endpoints | Endpoint | Method | Description | |----------|--------|-------------| | `/api/v0/mcp/info` | GET | Get MCP server information and capabilities | | `/api/v0/mcp/tools/list` | GET | List all available MCP tools | | `/api/v0/mcp/tools/call` | POST | Execute an MCP tool call | title: API Documentation version: 1.0.0 servers: - url: https://api.parallellabs.app security: - CompanyApiKey: [] - BearerAuth: [] CompanyId: [] tags: - description: >- Create, manage, and interact with AI agents that handle customer interactions across multiple channels including website chat, email, SMS, and voice. name: Agents - description: Generate text-to-speech audio using ElevenLabs. name: Audio - description: Execute browser automation tasks with natural language. name: Browser - description: OpenAI-compatible chat completions API. name: Chat - description: >- Manage companies and workspaces. Each company has its own agents, lists, sequences, and other resources. name: Companies - description: Manage team members and their access to companies. name: Company Users - description: >- AI content engine for generating and scheduling social media posts, articles, and marketing content. name: Content - description: >- SEO/AEO opportunity engine. Analyzes a domain against its competitors, search results, and AI assistant answers (ChatGPT, Google AI) to surface scored content opportunities, each with search volumes and a ready-to-generate brief. Workflow: 1) Create a project per ideal customer profile with content_research_createResearchProject — each project researches one domain against one ICP, so separate audiences stay separated rather than being blended into one result set. 2) Start a run with content_research_runResearchProject (charges credits up front, not refunded on failure; only one run per project can be active at a time). 3) Poll content_research_listResearchRuns until the newest run reports completed or failed. 4) Read results with content_research_listOpportunities, scoped by projectId. 5) Act on one with content_research_generateFromOpportunity to write the piece, content_research_trackOpportunity to monitor its keywords, or content_research_dismissOpportunity to hide it. name: Content Research - description: Organize employees into departments for better team structure. name: Departments - description: >- Browse and search platform documentation. Workflow: 1) Call documentation_listDocumentationCategories to see the top-level categories. 2) Drill into one with documentation_listDocumentationPages?parentId={id} to see its child pages. 3) Call documentation_getDocumentationPage with a page id to read the full Markdown content. 4) Use documentation_searchDocumentation for keyword search across pages — it returns short snippets so you can decide which page to open in full. IMPORTANT: If the documentation you need does not exist or is incomplete after you browse and search, call documentation_submitDocumentationRequest to file a request so the docs team can add it. name: Documentation - description: Manage your knowledge base documents for AI training and reference. name: Documents - description: >- AI employees are customizable personas you can chat with. To chat with an employee: 1) Use platform_list_companies to find your company ID, 2) List employees with employees_listEmployeesApi or employees_getEmployees, 3) Chat using employees_chatEmployee with the employeeId and your message. name: Employees - description: Generate AI images using DALL-E, Leonardo, and other providers. name: Images - description: Manage incoming messages and communications across channels. name: Inbox - name: Integrations - description: Manage API keys for programmatic access to the platform. name: Keys - description: Create and manage landing pages for lead capture and campaigns. name: Landing Pages - description: >- Lead generation and contact enrichment. Generate leads from demographic/firmographic filters, premade intent segments, and buyer-intent keywords, and enrich a person or company from any identifiers (name, email, company, domain, LinkedIn URL). Workflow: 1) Call leads_listFieldOptions with describe=true to learn the filter surface, then re-call with field= or group= for valid enum values — never guess enum strings. 2) Call leads_searchSegments to find premade segment externalIds (e.g. "b2b_12636") for interest/intent targeting. 3) Call leads_generateLeads with filters, segment ids, and/or audience buyer-intent keywords to fetch leads. 4) Call leads_enrichContact to get full contact details (emails, phones, ~75 fields) for a specific person or company — prefer it over web search for contact lookups. 5) To keep the leads, call leads_importLeadsToList with the same criteria plus a destination listId: it builds the full audience and writes every matching contact into that smart list as rows. The list must already exist (create one with lists_saveList first), and the import runs in the background — it returns a taskId immediately. Generating leads costs 1 data credit per call and a matched enrichment costs 2; importing costs 1 per contact imported and is gated on the FULL match count (the whole audience is built regardless of how many rows you import), so check totalAvailable with leads_generateLeads before importing; the field-options and segments endpoints are free. name: Leads - description: Manage smart lists for organizing contacts and data. name: Lists - description: >- Create, schedule, and send one-shot marketing email campaigns to a smart list, and track open/click performance. name: Marketing Campaigns - description: >- Model Context Protocol (MCP) server for AI assistants like Claude Desktop, Cursor, and Windsurf. Provides tools for full platform API access. name: Mcp - description: >- Store and retrieve conversation context and user preferences for AI personalization. name: Memories - description: List available AI models. name: Models - description: >- Track keywords across social media platforms (Reddit, Hacker News, LinkedIn, X, Quora) and discover relevant conversations. Create monitors to track specific keywords, receive notifications when mentions are found, and generate AI-powered reply suggestions to engage with your audience. name: Monitors - name: Organizations - name: People - description: Organize work into projects for better task management. name: Projects - description: >- Manage automated outreach sequences for email, SMS, and multi-channel campaigns. name: Sequences - description: >- Create and manage support tickets, post follow-up messages on tickets, and track their status. name: Support - description: Organize and categorize resources with custom tags. name: Tags - description: Track API usage, credits, and billing information. name: Usage - description: Generate AI videos using fal.ai models. name: Video - description: Manage voice clones and text-to-speech voice options. name: Voices paths: /api/v0/research/projects: get: tags: - Content Research summary: List all content research projects for a company. description: >- Each project targets one domain and one ideal customer profile. A company can have many, and opportunities are scoped per project. operationId: content_research_listResearchProjects parameters: - description: Company ID that owns the research projects in: query name: companyId required: true schema: description: Company ID that owns the research projects type: string responses: '200': content: application/json: schema: description: All research projects for the company properties: projects: description: Research projects owned by this company items: description: >- A content research project. Each project researches one domain against one ideal customer profile, so separate ICPs or product lines should each get their own project rather than sharing one. properties: companyId: description: Owning company ID type: string competitorDomains: description: >- Competitor domains compared against this project's domain items: type: string type: array createdBy: description: UID of the user who created the project type: string created_date: description: Creation timestamp format: date-time type: string domain: description: The domain being researched, e.g. "yourcompany.com" type: string frequency: description: >- How often the project auto-runs. One of: manual, weekly, monthly. "manual" means it only runs when triggered. enum: - manual - weekly - monthly type: string id: description: Project ID (UUID) type: string idealCustomerProfileId: description: >- ICP this project targets. Drives the relevance score and the content briefs. type: string lastRunAt: description: When the project last ran format: date-time type: string name: description: Human-readable project name type: string seedKeywords: description: Seed keywords the research pipeline expands from items: type: string type: array status: description: 'Project status. One of: active, archived.' enum: - active - archived type: string updated_date: description: Last update timestamp format: date-time type: string type: object type: array type: object description: All research projects for the company '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Company ID required '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: Invalid credentials '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: Unauthorized components: schemas: Error: properties: error: description: Error message type: string type: object securitySchemes: CompanyApiKey: description: >- Company API key - scoped to a specific company. Generate from the Integrations page in your dashboard. in: header name: X-API-Key type: apiKey BearerAuth: description: >- Bearer token authentication. Can use either a Company API Key or a Personal Access Key (starting with pak_). Personal Access Keys require X-Company-ID header. scheme: bearer type: http CompanyId: description: >- Required when using Personal Access Keys. Specifies which company to access. in: header name: X-Company-ID type: apiKey ````