Appearance
HTTP API
The REST API behind Instructions Manager. Use it when you need to do something the SDK does not: publish new prompt content from your own application, or discover what prompts and projects a key can reach.
INFO
If all you need is to read the active version of a prompt at runtime, use the elsai-prompts SDK instead. It handles environment checks, variable rendering and error types for you. This section is for the cases the SDK does not cover.
When to use which
| You want to… | Use |
|---|---|
| Load a reviewed prompt at runtime | SDK |
| Publish new content from your own UI or a CI job | Publishing |
| Let users pick a prompt from a list | Discovery |
| Read a prompt from a language with no SDK | Reading |
Availability
The HTTP API is not identical on SaaS and on-prem. Publishing and discovery are on-prem features; the read path is on both. Check this table before you build.
| Endpoint | SaaS | On-prem |
|---|---|---|
GET /prompts/active-prompt-version | ✅ | ✅ |
POST /prompts/active-prompt-version | ❌ | ✅ |
POST /skills/active-version | ❌ | ✅ |
GET /prompts — list | ❌ | ✅ |
GET /skills — list | ❌ | ✅ |
GET /skills/whoami, resolve, by-name, diff, bundle | ✅ | ✅ |
GET /skills/discover — marketplace search | ✅ | ❌ |
API key read / write scopes | ❌ | ✅ |
| Publishing flows and the AI reviewer | ❌ | ✅ |
✅ available · ❌ not on this deployment
On SaaS the read endpoint has a trailing slash (/prompts/active-prompt-version/); on-prem it does not. Both accept either — the server redirects.
Base URL
Your deployment. On-prem that is whatever your team runs, e.g. https://prompts.your-company.com. Everything below is relative to it.
bash
export IM_URL="https://prompts.your-company.com"
export IM_KEY="elsai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Conventions
- Request and response bodies are
application/json. - Timestamps are UTC, ISO 8601.
- Errors carry a machine-readable
code— branch on that, not on the message or the body shape. See Errors. - Call every endpoint server-side only. The key is a credential and must never reach a browser or mobile app.
What you need to start
One value comes from your Instructions Manager team. The rest you discover.
| Value | How you get it |
|---|---|
| API key | From the team. Secret. |
project_id | GET /skills/whoami |
prompt_name | GET /prompts |
| The project's publishing flow | Returned by the listings, and on every publish response |
Where to go next
Authentication
API keys, read and write scopes, and why a write key alone may still not publish.
→Discovery
Find the projects, prompts and skills a key can reach.
→Publishing
Make new content the active version, with safe concurrent writes.
→Publishing flows
What a publish actually does — approver review, direct, or AI-assisted.
→INFO
Integrating engineers may also want the precise contract document, which this section is the readable form of: docs/publish-api/api-contract.md in the Instructions Manager repository. It carries the exact request and response shapes for every endpoint.