canonical: https://jentic.com/apis/octavehq.com/octavehq

# Octavehq Octave API

Octave HQ exposes its agent platform through a public v2 API focused on listing the AI agents configured in a workspace. The platform's agents cover prospector, content, email, enrichment, qualification, and call-preparation roles aimed at outbound sales workflows. The published surface in this spec is intentionally narrow - listing agents - and provides the entry point external tools need to discover what agents exist before triggering deeper, account-specific actions in Octave.

## For AI agents

List the AI sales agents configured in an Octave HQ workspace through the public v2 API.

## Scope

Does not handle agent execution, CRM writes, or email sending - use for listing Octave HQ AI agents only.

## Capabilities

- List the AI agents configured in an Octave HQ workspace via `/agents/list`
- Discover prospector, content, email, and enrichment agents available to the account
- Audit which agents are deployed before triggering deeper Octave workflows
- Sync the catalogue of Octave agents into an internal agent registry
- Verify access to the Octave v2 API with a simple list call

## Use cases

### Octave Agent Inventory Audit

Audit which AI agents are configured in Octave by calling `/agents/list` and comparing the result to the expected inventory. Useful for revenue operations teams who need to know which prospector, content, email, enrichment, qualification, and call-preparation agents are live before approving a campaign. The single-endpoint scope keeps the integration trivial.

Example prompt: Call `/agents/list` and return the names and types of all configured agents.

### Internal Agent Registry Sync

Synchronise the catalogue of Octave agents into an internal agent-registry tool by polling `/agents/list` on a schedule and writing the result into an internal table. Helps RevOps and engineering teams maintain a single source of truth for which third-party agents are connected to which workspaces. The endpoint is read-only, so the sync carries no risk of changing Octave configuration.

Example prompt: Call `/agents/list` nightly and upsert the rows into the internal agents table keyed by Octave agent ID.

### Pre-Campaign Readiness Check

Run a pre-campaign readiness check by calling `/agents/list` and verifying that the prospector, email, and qualification agents required for the workflow exist before launching outbound. If any expected agent is missing the campaign is held until configuration is fixed. Fits well into a CI-style preflight job ahead of large outbound bursts.

Example prompt: Call `/agents/list` and assert that agents named 'prospector' and 'email' are present, otherwise abort the campaign.

### AI Agent Octave Discovery

An orchestrating AI agent can call Octave through Jentic to discover what specialised sales agents are available to the account before deciding which workflow to invoke. The agent finds `/agents/list` by intent, executes it, and uses the response to plan downstream actions. Credentials remain in your Jentic One instance throughout.

Example prompt: Use Jentic to call `/agents/list` and return the count of agents grouped by type.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/agents/list` | List all configured Octave agents |

## Key resources

- **Agents** — List the AI sales agents configured in an Octave HQ workspace.

## Why Jentic

- **Setup:** Wiring the Octave API by hand means setting up its api_key header, targeting the app.octavehq.com/api/v2 host, and parsing the agent list yourself. Through Jentic you install once, import Octave from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** The Octave API exposes a single read operation and no resource id in the URL path, so scoping is by operation: you limit the agent to the one operation it needs, listing Octave HQ AI agents, and it can call nothing else.
- **Credential handling:** Your Octave API key is stored once, encrypted, by your own Jentic One instance and injected into the api_key header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list AI sales agents in Octave', and Jentic returns the `/agents/list` operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Apollo.io API** — B2B prospecting database with email and dialer
- **Instantly API** — Cold-email sending platform with deliverability tooling
- **Outreach API** — Sales engagement platform for sequences and dialer
- **Salesloft API** — Sales engagement and revenue orchestration

## FAQ

### What authentication does the Octave API use?

An API key supplied via the api_key header. Jentic stores the key encrypted in its vault and injects it at execution time so the raw secret never enters the agent's prompt.

### Can I list all my Octave agents through this API?

Yes - that is exactly what the `/agents/list` endpoint returns. The response includes the agent identifier and type (prospector, content, email, enrichment, qualification, call preparation) for each agent configured in the workspace.

### What are the rate limits for the Octave API?

Octave does not publish a hard quota in the spec. Cache the agent list - it changes infrequently - and avoid polling the endpoint more than once a minute. Respect any 429 responses with exponential backoff.

### How do I list agents through Jentic?

Search Jentic for 'list Octave AI agents', load the schema for `/agents/list`, then execute. With pip install jentic the call is await client.search(...), await client.load(...), await client.execute(...) inside an asyncio.run wrapper.

### Does this API let me trigger an Octave agent run?

The single endpoint exposed in this spec is `/agents/list` - agent execution is not part of the public v2 surface. Trigger runs through the Octave UI or contact Octave for any workflow that needs programmatic agent execution.

### Is the Octave API free?

API access is tied to an Octave subscription. Confirm tier-specific entitlements in your Octave dashboard - there is no standalone free API tier in the spec.

### Can I limit what my agent is allowed to do with the Octave API?

Yes. The Octave API exposes a single read operation, listing the AI sales agents in a workspace via `/agents/list`, so you scope access at the operation level: in your self-hosted Jentic One instance you allow the agent only that one list operation and it can call nothing else. Because you host Jentic One yourself, your own rules decide which operations and which stored credentials the agent may use, and the Octave API key is injected at execution time rather than exposed to the agent. Since `/agents/list` carries no resource id in the path and only reads, the agent cannot modify Octave configuration, trigger runs, or reach any other endpoint.