Docs index

REST API endpoints

Endpoint list with methods, paths, scopes, request schemas, and response schemas.

Context guidance: Use when implementing or calling the REST API.

Endpoint summary

Request and response schemas are available in /docs/endpoints.json.

Credits

  • GET /api/v1/credits. Fetch the shared account credit-pool summary for the authenticated API key, current-key usage counters, the active search rate card, and billing semantics for each public API operation.
  • GET /api/v1/credits/status. Lightweight rolling-window credit status for the authenticated API key owner. Returns { tier, limit, used, remaining, window_start, window_days, reset_at, as_of }. Mirrors the X-Carl-Credits-* response headers emitted on every authenticated call. Safe to poll — remains reachable at or over the credit ceiling.

Communications

  • POST /api/v1/communications/capabilities. Resolve the acting user, target identity, and per-channel readiness for Super Carl direct messages, Super Carl invites, Super Carl referrals, Gmail sends, LinkedIn sends, X sends, and Instagram sends. Scopes: communications.
  • POST /api/v1/communications. Create a generic outbound communication record and send, invite, request referral, save a durable draft, or dry-run delivery through one of the supported channels. Scopes: communications.
  • GET /api/v1/communications/:communicationId. Fetch a communication record with normalized status, recent events, task metadata, reasoning lookup, and artifact URLs. Scopes: communications.
  • POST /api/v1/communications/history. Fetch prior visible communication history for a resolved target before drafting or sending. Scopes: communications.
  • POST /api/v1/communications/:communicationId/cancel. Cancel a queued or in-progress communication when the underlying channel supports cancellation before dispatch. Scopes: communications.
  • GET /api/v1/communications/:communicationId/events. Fetch the append-only communication event log. Scopes: communications.
  • GET /api/v1/communications/:communicationId/stream. Server-sent events stream for communication status changes, artifacts, and completion. Scopes: communications.
  • GET /api/v1/communications/:communicationId/artifacts/:filename. Proxy an artifact or screenshot attached to a communication. Scopes: communications.

People search

  • POST /api/v2/search/people/query. Run a natural-language people search. The service converts the text to typed filters and returns the applied request with matching people rows. Scopes: search.
  • POST /api/v1/search/people. Run a full people search or direct lookup by LinkedIn username or full LinkedIn profile URL. The description (or query alias) is auto-translated into AdvancedFilters by default; pass filters/search_metadata for explicit structured constraints. New lookups are enriched automatically. Set include_evidence_text=true or include_evidence_json=true to inline profile evidence for eval or LLM ranking workflows. Person rows include requester-relative previous-correspondence fields across synced/API channels when a Super Carl user identity is resolved. Scopes: search.
  • POST /api/v1/search/people/preview. Run a preview people search (auto-translated description/query, no enrichment, not enrichable). LinkedIn lookup is not supported. include_evidence_text is optional when you need inline profile evidence on preview rows. Scopes: search.
  • POST /api/v1/search/people/enrich. Re-run a full search with enrichment enabled using a search_id. Provide target_user_id to enrich one user, or omit it to enrich the current page of results. include_evidence_text can be supplied here even if the original search omitted it. Scopes: enrich.

Profiles

  • GET /api/v1/profiles/:id/chunks. Fetch cached profile chunks (no refresh). Scopes: profiles-read.
  • GET /api/v1/profiles/:id/text. Fetch profile text ready for LLM embeddings or contextual matching. Scopes: profiles-read.
  • GET /api/v1/profiles/:id. Fetch a profile snapshot by user id. Scopes: profiles-read.

Companies

  • POST /api/v1/companies/search/preview. Search companies in preview or detailed mode. Natural language queries are translated into company filters; returns a company search_id for follow-on people search joins. Set result_mode=detailed to expand each row with richer company fields, and include_evidence_text=true to inline evidence text built from stored company docs/posts. Scopes: search.

Jobs

  • POST /api/v1/search/jobs/preview. Natural-language job search scored against the viewer social-graph overlay. Accepts the full AdvancedFilters doc (hiring.*, companies.include/exclude, industries, company_stage, locations), including hiring.workplace_types for derived remote/hybrid/onsite/unknown filtering and hiring.published_within_days/published_after/published_before for hard posting-date filters. Each result row is decorated with a network block summarizing 1st/2nd-degree connections the viewer has at the posting company. Scopes: search.
  • POST /api/v1/search/jobs/with-people. The 'map a job to a path in' surface. Groups job_search_preview results by company and returns an inline slice of the viewer's 1st/2nd-degree people at each company. Billed as one preview search; sub-queries are linked via parent_search_activity_id. Scopes: search.

Other

  • GET /api/v1/contacts/reconciliation/schema. Return the public contact reconciliation row schema, supported modes, review actions, and batch limits for agent-assisted spreadsheet reconciliation. Existing MCP connector keys with the legacy search scope can use this read-only compatibility path. Scopes: contacts-read, search.
  • POST /api/v1/contacts/delegate-resolve. API-key-only batch contact resolver for integrations that need to resolve contacts from the perspective of a supplied delegate person instead of the API key owner. The delegate is required and can be supplied by Super Carl id or LinkedIn URL/username. The endpoint accepts up to 100 contacts per call and returns compact resolved-profile projections plus evidence/reasons. It is intentionally not exposed through MCP or OAuth connector scopes. Scopes: contacts-delegate-resolve.
  • POST /api/v1/contacts/reconciliation/runs. Create a bounded contact reconciliation run for a user-supplied spreadsheet or agent-normalized contact sheet. This sets up workflow/audit state only; applying changes still requires contacts-write. Scopes: contacts-read, search.
  • POST /api/v1/contacts/reconciliation/runs/:runId/batches/preview. Preview up to 100 normalized spreadsheet rows before applying them. Preview writes audit rows for the reconciliation run but does not mutate contact state, and remains available to existing MCP connector keys with the legacy search scope. Scopes: contacts-read, search.
  • POST /api/v1/contacts/reconciliation/runs/:runId/batches. Apply a reviewed batch of up to 100 normalized spreadsheet rows. Likely matches remain candidates until a later explicit confirm action. Scopes: contacts-write.
  • GET /api/v1/contacts/reconciliation/runs/:runId. Read reconciliation run status, aggregate row summary, and recent batch metadata. Scopes: contacts-read, search.
  • POST /api/v1/contacts/reconciliation/runs/:runId/finalize. Finalize a reconciliation run after reviewed batches are applied. Scopes: contacts-write.
  • GET /api/v1/contacts/reconciliation/review. List contact review entities in the same buckets exposed by the incoming/review tab, including likely_match, needs_review, unresolved, approved, and ignored. Scopes: contacts-read, search.
  • POST /api/v1/contacts/reconciliation/review/bulk. Apply up to 100 explicit review actions in one call. Bulk confirm can use entity_ids alone to confirm each row's stored proposed/top candidate, or items with per-row candidate_user_id overrides. Scopes: contacts-write.
  • GET /api/v1/contacts/reconciliation/review/:entityId/candidates. Fetch candidate Super Carl user matches for one contact review entity before confirming or rejecting. Scopes: contacts-read, search.
  • POST /api/v1/contacts/reconciliation/review/:entityId/confirm. Confirm one specific candidate user for a contact review entity. This is the explicit promotion step for likely matches. Scopes: contacts-write.
  • POST /api/v1/contacts/reconciliation/review/:entityId/:action. Review mutation endpoint for needs-review, not-a-match, ignore, and restore actions. These mirror the incoming/review tab controls. Scopes: contacts-write.

Other

  • POST /api/v1/search/posts/preview. Direct post/activity search. Supports a hard known-author cohort via filters.posts.author_user_ids (UUIDs) or author_user_id_ints (positive integers), literal mentions, expanded topic keywords, authored-account type, action types, engagement counts, date windows, and target constraints. Returned post rows use a Super Carl post id suitable for post://<id> inline references; ingestion-provider identifiers are not part of the API contract. For companies qualified by official posts, combine author_entity_types:["company"] with action_types:["post"] and with_companies:true; matching company actors are deduped into answer-ready companies[] rows with compact matched_posts evidence and explicit resolved/observed identity status. Without with_companies:true, the same filters remain post-primary. Returns matching post rows plus a people_search_binding for pivoting into profile search. Scopes: search.
  • POST /api/v1/search/posts/with-people. Post/activity search plus a deduped people set derived from matching person actors/authors. Set with_companies:true to additionally request the same PostMatchedCompany[] cohort as preview. Use for post-first "who" questions, then execute people_search_binding when full profile search, relationship detail, or additional structured constraints are needed. Scopes: search.

Other

  • GET /api/v1/projects. List active projects for the authenticated owner or delegate. Projects are the public name for assignment workspaces. Pass current_project_id for an MCP/session-bound project that must be surfaced even when generic list filters would hide it. Scopes: communications.
  • GET /api/v1/projects/:projectId. Fetch one project. Set include_targets=true to inline targets, and include_search_results=true to include the search-results cache. Scopes: communications.
  • GET /api/v1/projects/:projectId/targets. List active included targets for a project, excluding the project owner. This is the standalone API equivalent of the product target list. Scopes: communications.
  • POST /api/v1/projects/:projectId/targets. Add one or more people to a project shortlist. This is the standalone API equivalent of adding assignment targets in-product. Scopes: communications.
  • DELETE /api/v1/projects/:projectId/targets. Remove one or more people from a project shortlist by soft-clearing is_included. Pass remove_all=true only when intentionally clearing the shortlist. Scopes: communications.
  • GET /api/v1/projects/:projectId/metrics. Fetch outreach metrics for a project, including response rates, schedule-link click rates, and status-count breakdowns. Scopes: communications.
  • PATCH /api/v1/projects/:projectId. Rename a project or update basic project fields such as description, pitch, status, discovery, and engagement mode. Scopes: communications.
  • PUT /api/v1/projects/:projectId/templates. Update saved project outreach/referral/engagement templates. Set clear_personalization=true to clear generated target messages for regeneration. Scopes: communications.
  • POST /api/v1/projects/:projectId/templates/generate. Generate or regenerate a saved project template against project context. Supported template_type values include email_subject_template, outreach_message_prompt, engagement_meta_prompt, engagement_prompt, pitch, referral_intro_prompt, referral_forward_note_prompt, and generalize_message_to_template. Scopes: communications.
  • POST /api/v1/projects/:projectId/messages/generate. Generate personalized target messages against saved project templates. This drafts/generates messages; it does not send them. Scopes: communications.
  • PUT /api/v1/projects/:projectId/target-users/:targetUserId/message. Save an exact draft message for one project target by target user id. This updates the reviewable project draft and does not send it. Scopes: communications.
  • PUT /api/v1/projects/:projectId/targets/:targetId/message. Save an exact draft message for one project target by assignment target row id. This updates the reviewable project draft and does not send it. Scopes: communications.
  • GET /api/v1/projects/:projectId/send-readiness. Read the project send-confirm readiness summary: ready target count, previewed/not-previewed/edited/stale breakdown, stale target ids, and delivery-channel buckets. Scopes: communications.
  • POST /api/v1/projects/:projectId/activate. Start delivery for a reviewed project. Eligible included targets are marked for dispatch, the project becomes active, and channel-specific queues handle LinkedIn daily caps and automatic resume. Scopes: communications.

Machine-readable JSON