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

# Jentic API

The Jentic API is the control plane for the Jentic platform: it lets agents and developers search the public API catalogue by intent, load operation schemas, and execute calls against any registered API through a single uniform surface. The 95 endpoints cover agent registration, credential vaulting, sandboxed execution, workflow runs, spec ingestion and validation, registry browsing, search, file uploads, and usage statistics. Authentication supports both bearer tokens (OAuth) and a personal agent API key (ak_*) sent in the Authorization header.

## For AI agents

Search a 7,000+ API catalogue by intent, load operation schemas, and execute calls - plus manage agent identities, vaulted credentials, sandboxes, and workflow runs.

## Scope

Does not host vendor data or replace vendor APIs - use for agent identity, credential vaulting, intent search, and sandboxed execution that fronts other APIs only.

## Capabilities

- Search the public API registry by natural-language intent and receive ranked operation matches
- Load operation and workflow schemas on demand so agents can call them without scraping vendor docs
- Execute API calls and Arazzo workflows through Jentic-managed sandboxes via Workflow Executions
- Provision and validate agent identities and personal API keys via the Agents endpoints
- Grant, list, and revoke vaulted credentials per agent so secrets never reach the model context
- Ingest new OpenAPI and Arazzo specs into the registry through the Ingest endpoints
- Read usage statistics and audit per-agent activity via the Stats endpoints

## Use cases

### Intent-Based API Discovery for Agents

Agents that need to perform a real-world task (send an email, create a ticket, charge a card) call Jentic search with the natural-language intent and receive ranked API operations with their input schemas. This replaces the 'tell the model about every tool' pattern with on-demand discovery, keeping context windows small and tool catalogues fresh as the registry grows.

Example prompt: POST a search query 'send a transactional email' to the Search endpoint and select the top-ranked operation by score for execution.

### Vaulted Credential Management

Production agents need API keys for many vendors without those keys ever entering the LLM context. The Credentials endpoints let an operator vault Stripe, SendGrid, HubSpot, and other secrets per agent, scoped per operation. At execution time Jentic injects the credential into the outbound call so the model only ever sees opaque references.

Example prompt: POST to the agent credential grant endpoint to attach a stripe-test credential to agent_123, then call execute and verify the credential is referenced by id rather than value.

### Sandboxed Workflow Execution

Multi-step Arazzo workflows run inside Jentic sandboxes that handle pagination, retries, and rate-limit backoff. A single workflow execution can chain calls across vendors (e.g. create a Stripe customer, log a HubSpot contact, send a SendGrid welcome) without the agent owning any of the intermediate state, and the Workflow Executions endpoints expose status, logs, and outputs.

Example prompt: POST to the workflow execution endpoint with workflow_id=onboard-customer and inputs={email, name}, then poll the status endpoint until completed and return the workflow outputs.

### Catalogue Contribution via Spec Ingestion

Vendors and contributors add new APIs to the catalogue by ingesting an OpenAPI document through the Ingest endpoints. Jentic validates, scores, and registers the spec so it becomes immediately searchable by every connected agent. Useful for partners who want their API to be discoverable to the agent ecosystem without joining each individual MCP host.

Example prompt: POST a candidate OpenAPI document to the Ingest endpoint and read the validation diagnostics from the response to confirm successful registration.

### AI Agent Integration via Jentic

Jentic itself is the agent integration. Agents start by validating their API key against `/api/v1/agents/validate-key`, then issue search and execute calls for any downstream vendor. Run Jentic One, the self-hosted execution layer, to get an ak_* personal agent key.

Example prompt: Run pip install jentic, set JENTIC_AGENT_API_KEY=ak_..., and call validate-key to confirm the agent identity, then issue a search to confirm catalogue access.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/agents/validate-key` | Validate an agent's API key |
| POST | `/api/v1/agents/grant-credential` | Attach a vaulted credential to an agent |
| GET | `/api/v1/agents/{agent_id}/credentials` | List credentials attached to an agent |
| POST | `/api/v1/agents/{agent_id}/regenerate-key` | Rotate an agent API key |

## Key resources

- **Agents** — Register agent identities, validate API keys, and grant credentials to specific agents.
- **Credentials** — Vault, list, and revoke per-agent credentials so secrets never enter model context.
- **Search** — Find API operations and workflows by natural-language intent.
- **Workflows** — Define and execute multi-step Arazzo workflows across multiple APIs.
- **Workflow Executions** — Read status, logs, and outputs of workflow runs.
- **Sandboxes** — Run API calls inside Jentic-managed isolated environments.
- **Specs** — Browse OpenAPI specs registered in the catalogue.
- **Ingest** — Submit new OpenAPI documents into the registry.

## Why Jentic

- **Setup:** Wiring the Jentic API by hand means managing agent keys, bearer and header auth, and per-agent credential grants yourself. Through Jentic you install once, import the Jentic API from the API Directory, store the agent key once, and your agent calls it.
- **Permission scoping:** The Jentic API puts the agent id in the URL path (`/api/v1/agents/{agent_id}/...`), so a rule can pin your agent to one identity: it can validate its key and read that identity's credentials. You choose the operations it may call, so a credential grant or key regeneration is not included unless you add it.
- **Credential handling:** Your Jentic agent key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'validate my agent key' or 'list an agent's credentials', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Anthropic Messages API** — Drive Jentic search and execute from a Claude reasoning loop using Anthropic's Messages API
- **OpenAI API** — Use OpenAI models as the reasoning layer that emits Jentic search queries and consumes execute results

## FAQ

### What authentication does the Jentic API use?

Two schemes: a Bearer token for OAuth-style sessions and a personal agent API key (format ak_*) sent via the X-API-Key header (modeled as APIKeyHeader in the spec). For agent integrations, the API key is the typical choice and is set via the JENTIC_AGENT_API_KEY environment variable.

### Can I search for API operations by natural-language intent with the Jentic API?

Yes - the Search endpoints accept a natural-language query and return ranked matches with their operation schemas. This is the primary discovery mechanism agents use to pick a tool at runtime instead of being preloaded with thousands of tool definitions.

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

Per-agent rate limits are documented at docs.jentic.com and are tied to the plan attached to your ak_* key. Free-tier keys have lower per-minute search and execute quotas than paid plans; check the Stats endpoint to see your current usage.

### How do I grant a vendor credential to my agent through Jentic?

Run pip install jentic, set JENTIC_AGENT_API_KEY, then POST to `/api/v1/agents/grant-credential` with the agent_id and the credential reference. After that, search and execute calls for that vendor will inject the credential automatically - the raw secret is never returned to the agent.

### Can I register my own API in the Jentic API Directory?

Yes - POST your OpenAPI document to the Ingest endpoints. Jentic validates it, scores its agent-readiness, and adds it to the searchable registry. New specs are typically discoverable to agents within minutes of successful ingestion.

### Is the Jentic API free?

Yes for the free tier, which covers most individual-developer usage. Paid plans add higher rate limits, more vaulted credentials, and team management. Run Jentic One, the self-hosted execution layer, to get an ak_* key.

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

Yes. Because you run Jentic One yourself, your own rules decide which Jentic API operations and credentials the agent may use. Since the agent id sits in the URL path (`/api/v1/agents/{agent_id}/...`), you can pin the agent to a single identity and allow only read operations, such as validating its key and listing that identity's credentials. Higher-impact calls like granting a vendor credential or regenerating an agent key stay blocked unless you explicitly add them.