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

# Hydracept Public API

The Hydracept Public API runs external AI capabilities, such as image.generate.v1, through one interface with durable jobs, receipts, and bring-your-own-key provider credentials. You list and describe capabilities, quote a charge before running, then invoke a capability directly or submit it as a job that can be listed, streamed as events, approved, rejected, cancelled, and read back as a result, receipt, and downloadable artifacts. Around that core it manages project model adapters and LoRA weights with stable aliases, multi-provider comparisons, pinned inference receipts and provenance manifests, webhook delivery endpoints with replay, provider connections and organization credentials, storage backends, projects, and a prepaid billing wallet.

## For AI agents

Discover and quote Hydracept AI capabilities, run them as invocations or durable jobs, read job results, receipts, and artifacts, and manage the LoRA adapters, provider connections, and webhook deliveries behind them.

## Scope

Does not train foundation models, host your own application, or replace the upstream provider accounts it connects to. Use for running and auditing AI capability calls through Hydracept only.

## Capabilities

- Search the capability list by task query and describe a capability with its execution targets and benchmarks
- Quote a capability charge before running it, then invoke it or submit it as a durable job
- Follow a job through its events, approve, reject, or cancel it, and fetch its result, receipt, and artifacts
- Register, upload, and revalidate LoRA model adapters and point stable aliases at specific versions
- Compare several providers on the same capability input and estimate the comparison cost first
- Connect upstream provider accounts with your own keys and bind them to a project and environment
- Register webhook delivery endpoints, list deliveries by job or state, and replay a failed delivery

## Use cases

### Agent-run AI jobs with receipts through Jentic

A developer's agent calls AI capabilities through Hydracept and keeps a receipt for each one. Through Jentic the agent finds the quote, job, and receipt operations by intent; the Hydracept API key is injected by the developer's own Jentic One instance, and a rule can confine the agent to one capability key so it cannot touch connections, keys, or the wallet.

Example prompt: Call POST `/v1/capabilities/{capability_key}/quote` with capability_key image.generate.v1 and the prompt input, submit POST `/v1/capabilities/image.generate.v1/jobs` with the same input, poll GET `/v1/jobs/{job_id}` until it finishes, then fetch GET `/v1/jobs/{job_id}/receipt`

### Brand-consistent image generation with LoRA adapters

Keep generated images on brand by registering a LoRA adapter for the project and referring to it through a stable alias. Uploads take the weights file and a displayName, aliases have immutable versions and explicit promotions, and a project default can map a capability to an alias, so jobs keep using the approved adapter until someone promotes a new one.

Example prompt: Call POST `/v1/adapters/upload` with the weights file and displayName 'Brand style v3', create an alias with POST `/v1/adapter-aliases` targeting the new adapter, then set it as the image.generate.v1 project default with PUT `/v1/adapter-defaults/{capability_key}`

### Provider comparison before switching

Decide between providers on evidence rather than guesswork. The comparison call runs the same capability input against several competitors, the estimate call prices that comparison first, and the competitor-options call lists the default providers to compare for a capability.

Example prompt: Call GET `/v1/capabilities/{capability_key}/comparisons/competitor-options`, price two of them with POST `/v1/capabilities/{capability_key}/comparisons/estimate`, then run POST `/v1/capabilities/{capability_key}/comparisons` with context and those competitors

### Reliable job notifications

Get notified when jobs finish instead of polling. A delivery endpoint takes a url and a signing secret, can be limited to chosen eventTypes, and every delivery attempt is listed with its state, filterable by endpoint or job, so a failed delivery can be found and replayed.

Example prompt: Call GET `/v1/deliveries` with jobId job_8f2 to find its failed delivery, then call POST `/v1/deliveries/{delivery_id}/replay` for it

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/capabilities` | List capabilities |
| POST | `/v1/capabilities/{capability_key}/quote` | Quote a capability charge |
| POST | `/v1/capabilities/{capability_key}/invoke` | Invoke a capability |
| POST | `/v1/capabilities/{capability_key}/jobs` | Submit a capability job |
| GET | `/v1/jobs/{job_id}/result` | Get a job result |
| GET | `/v1/jobs/{job_id}/receipt` | Get a job receipt |
| POST | `/v1/adapters/upload` | Upload and register LoRA weights |
| POST | `/v1/deliveries/{delivery_id}/replay` | Replay a delivery |

## Key resources

- **Capabilities** — Runnable AI capabilities with descriptions, execution targets, benchmarks, quotes, invocation, and jobs
- **Jobs** — Durable runs with events, approval, cancellation, results, receipts, artifacts, and variant selection
- **Model adapters and aliases** — LoRA adapters, uploads, suggestions, stable aliases with versions and promotions, and project defaults
- **Connections and credentials** — Upstream provider connections, organization credentials, bindings, rotation, and onboarding sessions
- **Deliveries** — Webhook delivery endpoints, delivery history, and replay
- **Provenance** — Pinned inference receipts, manifests, and lockfiles with verification
- **Organizations, projects, and billing** — Organizations, projects, environments, storage backends, wallet, and API keys

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 61 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 89 / 100
  - Developer Experience & Jentic Compatibility: 69 / 100
  - AI-Readiness & Agent Experience: 47 / 100
  - Agent Usability: 75 / 100
  - Security: 60 / 100
  - AI Discoverability: 47 / 100
- **View full report:** https://jentic.com/apis/hydracept.com/hydracept/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Hydracept Public API by hand means sending its bearer key, threading quote ids into job submissions, polling or streaming job events, and keeping track of projects, environments, and provider bindings. Through Jentic you install once, import Hydracept from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Hydracept puts the capability key and job id in the URL path (`/v1/capabilities/{capability_key}/...`, `/v1/jobs/{job_id}/...`), so a rule can pin your agent to one capability such as image.generate.v1. You choose the operations it may call, so destructive ones like deleting API keys or revoking provider credentials are not included unless you add them.
- **Credential handling:** Your Hydracept API 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 'generate an image' or 'get a job receipt', and Jentic returns the matching Hydracept operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Replicate API** — Run open-source models as hosted predictions
- **fal API** — Fast hosted inference for image and media models
- **OpenRouter API** — One API across many language model providers
- **Stability AI API** — Image generation models from Stability AI

## FAQ

### What authentication does the Hydracept Public API use?

Per its OpenAPI spec, the Hydracept Public API uses a Hydracept API key sent as a bearer token in the Authorization header. A handful of discovery operations, such as listing and describing capabilities, resolving a capability, and the agent-context call, need no credential. Through Jentic the key is stored encrypted by your own Jentic One instance and injected per call.

### Can I see the cost of a Hydracept job before running it?

Yes. POST `/v1/capabilities/{capability_key}/quote` and the matching estimate call return a charge quote for a given input, and the execution options on a job accept a quoteId and a maximumCharge. After a run, GET `/v1/jobs/{job_id}/receipt` returns the job's receipt and the wallet settlement call shows what was charged.

### Does Hydracept support bring-your-own-key provider credentials?

Yes. You can create connections to upstream providers with POST `/v1/connections`, store organization-level provider credentials, rotate them, and bind them to a project and environment. Those provider secrets live in Hydracept; through Jentic, your agent only uses the Hydracept API key.

### What are the rate limits for the Hydracept Public API?

The OpenAPI spec does not specify rate limits. Check Hydracept's documentation at https://api.hydracept.com for current limits.

### How do I run an image generation job with the Hydracept API through Jentic?

Search Jentic for 'submit an image generation job' to get POST `/v1/capabilities/image.generate.v1/jobs`, send the input, then poll GET `/v1/jobs/{job_id}` and fetch the output with GET `/v1/jobs/{job_id}/result.` To run it on your own infrastructure, install Jentic One from its GitHub repo and store your Hydracept key once.

### Is there a Hydracept MCP server?

You don't need an MCP server to give your agent Hydracept. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent finds the operations it needs on demand, without a large set of tool definitions sitting in its context.

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

Yes. For example, write a rule that allows only the quote and jobs operations under `/v1/capabilities/image.generate.v1` plus GET `/v1/jobs/{job_id}/result`, so the agent can price and run image jobs and read their output but cannot create API keys, rotate provider credentials, or open a wallet top-up session. Your Jentic One instance logs the calls it makes.