> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.askelephant.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.askelephant.ai/_mcp/server. # Scopes matrix This page summarizes the current scope policy for the public API. ## Live scope requirements | Endpoint | Method | Required scope(s) | Conditional scope(s) | Summary | | --------------------------------------------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | `/api/v1/oauth/token` | `POST` | None | None | Exchange OAuth credentials for an access token | | `/api/v2/transcript_comments/{transcript_comment_id}` | `GET` | `engagements:read`, `transcript_comments:read` | If the engagement is private: `engagements:private:read` | Get transcript comment | | `/api/v2/transcript_comments/{transcript_comment_id}` | `PATCH` | `engagements:read`, `transcript_comments:write` | If the engagement is private: `engagements:private:read` | Update transcript comment | | `/api/v2/transcript_comments/{transcript_comment_id}` | `DELETE` | `engagements:read`, `transcript_comments:write` | If the engagement is private: `engagements:private:read` | Delete transcript comment | | `/api/v2/companies` | `GET` | `companies:read` | None | List companies | | `/api/v2/companies` | `POST` | `companies:write` | None | Create company | | `/api/v2/companies/{company_id}` | `GET` | `companies:read` | None | Get company | | `/api/v2/companies/{company_id}` | `PATCH` | `companies:write` | None | Update company | | `/api/v2/companies/{company_id}` | `DELETE` | `companies:write` | None | Delete company | | `/api/v2/companies/{company_id}/crm_association` | `PUT` | `companies:write` | None | Set company CRM association | | `/api/v2/companies/{company_id}/crm_association` | `DELETE` | `companies:write` | None | Clear company CRM association | | `/api/v2/companies/{company_id}/engagements` | `GET` | `engagements:read` | If private engagements are included in the result set: `engagements:private:read`; if `expand=companies`: `companies:read`; if `expand=contacts`: `contacts:read`; if `expand=owner`: `users:read` | List company engagements | | `/api/v2/contacts` | `GET` | `contacts:read` | None | List contacts | | `/api/v2/contacts` | `POST` | `contacts:write` | None | Create contact | | `/api/v2/contacts/{contact_id}` | `GET` | `contacts:read` | None | Get contact | | `/api/v2/contacts/{contact_id}` | `PATCH` | `contacts:write` | None | Update contact | | `/api/v2/contacts/{contact_id}` | `DELETE` | `contacts:write` | None | Delete contact | | `/api/v2/contacts/{contact_id}/crm_association` | `PUT` | `contacts:write` | None | Set contact CRM association | | `/api/v2/contacts/{contact_id}/crm_association` | `DELETE` | `contacts:write` | None | Clear contact CRM association | | `/api/v2/engagements/{engagement_id}/transcript_comments` | `GET` | `engagements:read`, `transcript_comments:read` | If the engagement is private: `engagements:private:read` | List engagement transcript comments | | `/api/v2/engagements/{engagement_id}/transcript_comments` | `POST` | `engagements:read`, `transcript_comments:write` | If the engagement is private: `engagements:private:read` | Create engagement transcript comment | | `/api/v2/contacts/{contact_id}/engagements` | `GET` | `engagements:read` | If private engagements are included in the result set: `engagements:private:read`; if `expand=companies`: `companies:read`; if `expand=contacts`: `contacts:read`; if `expand=owner`: `users:read` | List contact engagements | | `/api/v2/engagements` | `GET` | `engagements:read` | If private engagements are included in the result set: `engagements:private:read`; if `expand=companies`: `companies:read`; if `expand=contacts`: `contacts:read`; if `expand=owner`: `users:read` | List engagements | | `/api/v2/engagements/{engagement_id}` | `GET` | `engagements:read` | If the engagement is private: `engagements:private:read`; if `expand=companies`: `companies:read`; if `expand=contacts`: `contacts:read`; if `expand=owner`: `users:read` | Get engagement | | `/api/v2/engagements/{engagement_id}/transcript_comments` | `GET` | `engagements:read`, `transcript_comments:read` | If the engagement is private: `engagements:private:read` | List engagement transcript comments | | `/api/v2/engagements/{engagement_id}/transcript_comments` | `POST` | `engagements:read`, `transcript_comments:write` | If the engagement is private: `engagements:private:read` | Create engagement transcript comment | | `/api/v2/engagements/{engagement_id}/contacts` | `PUT` | `engagements:write` | If the engagement is private: `engagements:private:write` | Replace engagement contacts | | `/api/v2/engagements/{engagement_id}/tags` | `PUT` | `engagements:write` | If the engagement is private: `engagements:private:write` | Replace engagement tags | | `/api/v2/engagements/{engagement_id}/transcript_timeline` | `GET` | `transcript_timelines:read` | If the engagement is private: `engagements:read` and `engagements:private:read` | Get engagement transcript timeline | | `/api/v2/tags` | `GET` | `tags:read` | None | List tags | | `/api/v2/tags` | `POST` | `tags:write` | None | Create tag | | `/api/v2/tags/{tag_id}` | `GET` | `tags:read` | None | Get tag | | `/api/v2/tags/{tag_id}` | `PATCH` | `tags:write` | None | Update tag | | `/api/v2/tags/{tag_id}` | `DELETE` | `tags:write` | None | Delete tag | | `/api/v2/users` | `GET` | `users:read` | None | List users | | `/api/v2/users/{user_id}` | `GET` | `users:read` | None | Get user | ## Notes * A valid credential without the route's required or conditional scope returns `403`. * `workspace:admin` can be used for full access across the current public API surface. * Engagement reads with `expand=companies`, `expand=contacts`, or `expand=owner` require the additional scopes shown above. * Engagement payloads always include `is_private`, but private engagements are only returned when the credential also has `engagements:private:read` or `workspace:admin`. * Transcript comment reads and writes for private engagements also require `engagements:private:read`. * Private engagement writes require `engagements:private:write` unless the credential has `workspace:admin`.