Reading a prompt

GET /prompts/active-prompt-version

Returns the currently active version of a named prompt. Available on SaaS and on-prem.

INFO

If you are in Python, use the SDK — it wraps this endpoint and gives you typed content, variable rendering and proper exception types. Call this directly when you are in another language, or when you need the raw response.

Request

The key goes in the query string here — this endpoint predates the header convention.

curl -s "$IM_URL/prompts/active-prompt-version\
?api_key=$IM_KEY\
&project_id=8112d9c4-8334-43dd-a3c0-436b5cf1f475\
&prompt_name=sampleAgent"

Parameter	Required	Notes
api_key	yes
project_id	yes
prompt_name	yes	exact and case-sensitive
environment	no	development | test | production

WARNING

No spaces anywhere in the URL. A stray space around a ? or & breaks the query parsing and the failure looks like a missing prompt rather than a malformed request.

Response

{
  "prompt_id": "3d7735aa-8e34-4e58-b5e9-e93181526403",
  "prompt_name": "sampleAgent",
  "kind": "instruction",
  "sha": "c8aceef013a8",
  "version_label": "v1.0",
  "content": {
    "kind": "instruction",
    "text": "Print the word \"hello\" exactly 3 times.",
    "system_prompt": ""
  },
  "environments": ["development", "test"],
  "published_via": null
}

shastring

Identifies this exact version. Keep it — publishing requires it as expected_active_sha.

kindstring

instruction, f_string, chat or structured. Determines the shape of content — see Prompt kinds.

contentobject

The prompt itself, shaped per kind.

published_viastring | null

How this version reached production. null — a human reviewed and approved it. "api" — published through this API. "direct" — published in the console without review, on a project whose flow allows it.

The environment filter

Passing environment asserts that the active version is released there. If it is not, you get 409 and the body tells you where it is released:

{
  "detail": {
    "message": "Active version is not released to the requested environment.",
    "available_environments": ["development", "test"]
  }
}

This is a guard, not a filter — it does not find you a different version. It exists so a production service fails loudly rather than quietly serving a prompt that was only ever approved for development.

Omit environment and you get whatever is active, regardless of release state.

Errors

Status	Meaning
404	invalid or revoked key, unknown project, unknown prompt, no active version, or no access
409	active version exists but is not released to the requested environment

DANGER

That 404 is deliberately ambiguous. Five different causes return byte-identical responses, so the endpoint cannot be used to discover which projects or prompts exist. It means "you get nothing" — not "the prompt is missing".

When debugging one, check in this order: the key is valid and not revoked, the key owner is a member of the project's organisation, the project_id is right, the prompt_name matches exactly including case, and something is actually active.

Next

Publishing

Use the sha you just read to publish new content safely.

→

Errors

Every status and code, and what to retry.

→