GET /v1/prompts/:promptId

Summary

This endpoint retrieves metadata about a published prompt. By default, it returns the latest published version; you can request a specific version by providing the optional versionId query parameter. The response includes the prompt's title, the version identifier and publication timestamp, a flag indicating whether the version is the latest, and a JSON Type Definition (JTD) describing the inputs that the prompt expects.

HTTP Request

GET /v1/prompts/:promptId?versionId=<versionId>

Path parameters

Parameter	Type	Required	Description
promptId	string	Yes	Unique identifier for the published prompt.

Query parameters

Parameter	Type	Required	Description
versionId	string	No	Identifier of a specific prompt version. When omitted, the latest published version is returned.

Response

Success (200 OK)

When the prompt exists, the server returns a JSON object whose status is "SUCCESS" and a data field containing the prompt metadata.

Field	Type	Description
promptId	string	Identifier of the published prompt.
title	string	Human-readable title of the prompt.
version.promptVersionId	string	Identifier of the returned prompt version.
version.publishedAt	string (ISO 8601)	Timestamp when the version was published.
version.isLatest	boolean	true if this version is the latest.
metadata.inputsJTD	object	JSON Type Definition describing the expected inputs.

Example response

{
  "status": "SUCCESS",
  "data": {
    "promptId": "01234567-89ab-cdef-0123-456789abcdef",
    "title": "Image caption generator",
    "version": {
      "promptVersionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "publishedAt": "2025-08-27T12:34:56.789Z",
      "isLatest": true
    },
    "metadata": {
      "inputsJTD": {
        "properties": {
          "textInputs": {
            "properties": {
              "image_description": { "type": "string" },
              "style": { "type": "string" }
            }
          },
          "imageInputs": {
            "metadata": {
              "imageCount": 1
            }
          }
        }
      }
    }
  }
}

Error responses

HTTP status	status code	Description
422	VALIDATION_ERROR	Invalid UUID or parameters.
404	NOT_FOUND_ERROR	The prompt/version does not exist.

See also

• List prompt versions: GET /v1/prompts/:promptId/versions
• Run a prompt: POST /v1/runs