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

# Auxen Headless API

The Auxen API deploys and manages private open-weight model endpoints and runs inference against them. It exposes operations to deploy a model, switch the model on a running deployment, change throughput, and pause or resume a deployment, each identified by a deployment id. Billing operations read the account balance, top up credits, and set per-deployment spending caps, while account-level agent keys and per-deployment inference keys keep management separate from calling.

## For AI agents

Deploy open-weight models to private endpoints and run inference on them: deploy, switch models, change throughput, pause or resume, and read billing, with chat completions on each deployment.

## Scope

Does not handle model training, dataset labeling, or fine-tuning. Use for deploying open-weight models and running inference on them only.

## Capabilities

- Deploy an open-weight model to a private endpoint and read its deployment id back
- Switch the model on a running deployment or change its throughput
- Run inference against a deployment through the Auxen-native or OpenAI-compatible chat endpoint
- Pause and resume deployments to control spend
- Read the account billing balance and set a per-deployment spending cap
- Register webhooks and inspect recent webhook deliveries for a deployment

## Use cases

### AI Agent Model Deployment

An AI agent spins up a private inference endpoint on demand without a developer clicking through a dashboard. Through Jentic the agent deploys an open-weight model, reads back the deployment id, and runs completions against it, while the account and deployment keys stay on the developer's own machine.

Example prompt: Deploy a model from the models list, capture the returned deployment id, and send a chat completion to confirm the endpoint responds

### Deployment Cost Control

Private model endpoints cost money while they run, so teams pause them when idle and cap spend per deployment. Auxen lets an agent pause a deployment, resume it when traffic returns, read the account credit balance, and set a spending cap on a single deployment.

Example prompt: Pause an idle deployment, then set a spending cap on it before resuming so it cannot overspend the account balance

### Live Model Switching

Teams iterate on which open-weight model serves a given endpoint. Auxen lets an agent switch the model on an existing deployment in place and adjust its throughput, so the endpoint URL stays stable while the model behind it changes.

Example prompt: Switch the model on a deployment to a newer open-weight model and raise its throughput for the expected load

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/deploy` | Deploy a model |
| GET | `/v1/deployments` | List your deployments |
| GET | `/v1/deployments/{deploymentId}` | Get a deployment |
| POST | `/v1/deployments/{deploymentId}/switch-model` | Switch the model on a deployment |
| POST | `/v1/deployments/{deploymentId}/pause` | Pause a deployment |
| POST | `/v1/{deploymentId}/chat` | Run inference on a deployment |
| GET | `/v1/models` | List available models |
| GET | `/v1/billing/balance` | Get account billing snapshot |

## Key resources

- **Models** — List the open-weight models available to deploy and read a single model
- **Deployments** — Deploy, read, update, delete, pause, resume, and switch the model on private endpoints
- **Inference** — Run Auxen-native or OpenAI-compatible chat completions against a deployment
- **Billing** — Read the account balance, top up credits, and manage auto-recharge and spending caps
- **Webhooks** — Register webhooks and inspect recent deliveries and test events

## 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:** 43 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 59 / 100
  - Developer Experience & Jentic Compatibility: 64 / 100
  - AI-Readiness & Agent Experience: 20 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 64 / 100
- **View full report:** https://jentic.com/apis/auxen.ai/auxen/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 Auxen by hand means handling two token types, its account-level agent key and per-deployment inference keys, and polling deployment state yourself. Through Jentic you install once, import Auxen from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Auxen puts the deployment id in the URL path (`/v1/deployments/{deploymentId}/...`), so a rule can pin your agent to one deployment: it can run inference and read status for that deployment and nothing else. You choose which operations it may call, so destructive ones like deployment deletion are not included unless you add them.
- **Credential handling:** Your Auxen keys are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'deploy a model' or 'run a chat completion', and Jentic returns the matching Auxen operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Replicate** — Replicate runs hosted open-source models on shared cloud GPUs instead of your own private endpoints.
- **Hugging Face** — Hugging Face hosts and serves open models and datasets across its hub and inference endpoints.
- **OpenAI** — OpenAI serves hosted frontier models through a managed API.

## FAQ

### Is there an Auxen MCP server?

You don't need an MCP server to give your agent the Auxen API. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls it. Operations are discovered on demand, so nothing extra is loaded into the agent's context.

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

Yes. Write a rule that allows only the inference and status-read operations under one deployment id, so the agent can run completions and check that deployment without deleting it or touching billing, and every call is logged.

### What authentication does the Auxen Headless API use?

The Auxen API authenticates with bearer tokens: an account-level agent key authorizes deployment and billing operations, and a per-deployment inference key authorizes chat calls on a single deployment, per its OpenAPI spec. Through Jentic each token is stored encrypted by your own Jentic One instance and injected at call time, so it never reaches the agent's prompt or logs.

### Can I run a chat completion against a deployment with the Auxen API?

Yes. Each deployment exposes an Auxen-native chat endpoint and an OpenAI-compatible chat completions endpoint, both called with that deployment's inference key so you can hand the key to a downstream service without giving up management rights.

### How do I deploy an Auxen model through Jentic?

Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, then import the Auxen API from the Jentic API Directory and store your agent key. Your agent searches for 'deploy an open-weight model' and Jentic returns the deploy operation with its input schema. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### What are the rate limits for the Auxen Headless API?

The Auxen OpenAPI spec does not define request rate limits. Auxen meters usage by USD-denominated credits and the per-deployment throughput you set, so check your plan's throughput tier and credit balance for the ceilings that apply.