AI review API

Generate an AI review from data supplied by your application. This endpoint uses a dedicated API key created in Settings → AI in the web app.

POST https://api.epismo.ai/v1/reviews

Review your own data without creating cases or playbooks. Include the information needed for the review in context. Web search is not available.

Create and manage a key

Select the workspace or your personal account in the web app, then open Settings → AI → API keys. Enter a name and choose an expiration: 7, 30, or 90 days, 1 year, or no expiration. Copy the secret when it is created; it is only shown once.

• Workspace keys belong to the workspace and consume its shared credits. Only owners and admins can manage them. The workspace must have an active or trial subscription.
• Personal keys belong to you and consume your personal credits.
• Allow Epismo AI must be enabled for the key's owner.

The list shows the creator, creation time, expiration, and approximate last use. Revoke a key to stop its use immediately. You can permanently delete it after revocation; this does not remove its recorded usage. If you lose a secret, revoke the key and create another one. Key management is available through the web UI.

Track usage by API key in Credit management. Deleting a key keeps its recorded usage but groups it under Unknown.

Request

Send these headers:

Requests use the credits of the personal account or workspace that owns the key. You do not need to specify a billing account in the body.

The entire request body must fit within 600,000 bytes. Unknown fields are rejected. Omit optional fields instead of sending null.

Minimal example

Set EPISMO_API_KEY to your secret. The minimal request only needs context in the body.

curl https://api.epismo.ai/v1/reviews \
  --header "Authorization: Bearer $EPISMO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"context":{"messages":[
    {"role":"user","content":"What is 2 + 2?"},
    {"role":"assistant","content":"5."}
  ]}}'

Structured output and health assessment example

Just as Epismo evaluates case health internally, you can pair instructions with output_schema to produce a strictly typed JSON object instead of free-form prose. This allows you to evaluate operational health (healthy, at_risk, critical, or unknown), generate evidence-grounded summaries, and extract discrete risk factors and next actions.

curl https://api.epismo.ai/v1/reviews \
  --header "Authorization: Bearer $EPISMO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "instructions": "Objectively diagnose the health of the work as healthy, at_risk, critical, or unknown based on the supplied records. Avoid unsupported assumptions, and use unknown if the evidence is insufficient for a reliable diagnosis.",
    "context": {
      "milestone": "v2.0 Release",
      "records": [
        {"timestamp": "2026-10-25", "content": "Core API implementation complete and deployed to staging."},
        {"timestamp": "2026-10-26", "content": "Load testing revealed a 15% timeout rate on the payment gateway. Root cause under investigation."}
      ]
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "health": {
          "type": "string",
          "enum": ["healthy", "at_risk", "critical", "unknown"],
          "description": "Evidence-based health diagnosis"
        },
        "summary": {
          "type": "string",
          "description": "Current situation and primary reason for the health diagnosis (under 280 characters)"
        },
        "risks": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Concrete risks or stalled dependencies threatening the goal"
        },
        "next_actions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "reason": { "type": "string" }
            },
            "required": ["title", "reason"]
          },
          "description": "Recommended next actions"
        }
      },
      "required": ["health", "summary", "risks", "next_actions"]
    }
  }'

The response output conforms strictly to the supplied schema without extraneous keys:

{
	"output": {
		"health": "at_risk",
		"summary": "Core features are deployed, but frequent payment gateway timeouts during load testing threaten the on-schedule release.",
		"risks": ["Intermittent payment gateway failures under load"],
		"next_actions": [
			{
				"title": "Investigate payment gateway timeout bottlenecks",
				"reason": "Identify root cause and tune connection pools and retry policies"
			}
		]
	},
	"credits_consumed": 5
}

Enforcing strict schemas and enums guarantees type safety for downstream systems, making it straightforward to trigger automated alerts when health drops to at_risk or critical, sync status to internal dashboards, or drive CI/CD gates.

Response

The request returns HTTP 200 with the result when generation completes.

{
	"output": {
		"content": "The answer is incorrect: 2 + 2 equals 4, not 5."
	},
	"credits_consumed": 3
}

This is an illustrative response; content and credit usage vary. output follows output_schema when supplied. Credit usage depends on the model and actual token usage. Results are not saved as report history; keep the response in your application if needed.

Retries and errors

Idempotency-Key is optional. When omitted, each call starts a new review and can consume credits again, even with identical input. Empty or malformed headers are rejected with 400.

For applications that retry requests, generate a UUID before the first attempt and include it in the header:

IDEMPOTENCY_KEY=$(uuidgen)
# Add this header to curl, reusing the variable for retries:
# --header "Idempotency-Key: $IDEMPOTENCY_KEY"

Reuse the same Idempotency-Key and identical input when retrying with the same API key. A completed request returns its saved result without another generation or charge. Reusing the UUID with different input returns a conflict. An operation already running with that key can also return a conflict; wait before retrying the identical request. Use a new UUID for a new review.

Errors have this shape:

{
	"error": {
		"message": "A review API key is required as a Bearer token."
	}
}

Use bounded backoff for transient errors. After a network failure or uncertain response, reuse the original UUID if one was supplied. Without a supplied key, retrying can generate another review and consume additional credits.