Skip to content
Developer docs

API & SDK

Integrate Promptsheon with automation, CI, the command line, or a custom control plane without coupling to the web console.

Choose your integration surface

HTTP API

Use the authenticated Fastify API for releases, evaluations, audit, workspaces, and operations.

CLI

Use repository-local commands when humans or CI need a scriptable workflow.

SDK

Embed capability publishing and tracing in a service without hand-building HTTP requests.

Authentication

Send a bearer API key with every protected request. Keys are hashed at rest, scoped to an organization, and assigned a role. Do not put keys in browser bundles, source control, URLs, or logs.

curl http://localhost:8080/api/releases \
  -H 'Authorization: Bearer pk_your_key_here' \
  -H 'Accept: application/json'

Use the TypeScript SDK

The workspace SDK is a small typed client over the same HTTP contract. It uses the platform's native fetch, so it works in Node 18+, server runtimes, and worker environments. Keep the API key on the server. The package is currently workspace-private, so build it from a checkout:

pnpm --filter @promptsheon/sdk build
import { PromptsheonClient } from '@promptsheon/sdk';

const client = new PromptsheonClient({
  baseUrl: process.env.PROMPTSHEON_API_URL ?? 'http://127.0.0.1:8080',
  apiKey: process.env.PROMPTSHEON_API_KEY,
});

const repositories = await client.listRepos(process.env.PROMPTSHEON_WORKSPACE_ID!);
const suite = await client.createSuite({
  capabilityId: process.env.PROMPTSHEON_CAPABILITY_ID!,
  name: 'refund-regression',
  passThreshold: 0.92,
  initialGraders: [{ name: 'exact-match', kind: 'exact', weight: 1, config: {} }],
});

console.log({ repositories, suiteId: suite.suite.id });

SDK methods throw an Error containing the HTTP method, path, status, and response body for non-success responses. Catch it at your job boundary and preserve the request ID from the raw response in production integrations.

Use the CLI in CI

The CLI reads its endpoint and bearer key from environment variables. Add --json when another pipeline step consumes the result, and use --dry-run before allowing a mutating command to run in a new environment.

export PROMPTSHEON_API_URL=http://127.0.0.1:8080
export PROMPTSHEON_API_KEY=pk_your_key_here
export PROMPTSHEON_WORKSPACE_ID=workspace-uuid

promptsheon login
promptsheon repos list --json
promptsheon eval gate "$REPO_ID" --json
promptsheon release get "$RELEASE_ID" --json
promptsheon release approve "$RELEASE_ID" --dry-run --json
promptsheon manifest scan "$MANIFEST_HASH" --json

For a checkout of this repository, build the workspace CLI with pnpm --filter @promptsheon/cli build and invoke node packages/cli/dist/index.js until the package is published.

HTTP conventions

  • Request bodies and query strings are validated at the route boundary.
  • Errors use { error: { code, message } }; validation errors may include issues.
  • Use X-Request-Id to correlate client logs with server logs.
  • Use Idempotency-Key for retried mutating operations that support it.
  • Health and readiness endpoints are available at /api/health and /api/ready.

CI release shape

# validate and evaluate the candidate
pnpm test
pnpm typecheck
pnpm --dir frontend test:e2e

# inspect the candidate and approval state
promptsheon release get <release-id> --json
promptsheon release approve <release-id> --dry-run --json

Keep evaluation output, release identifiers, and audit references as build artifacts. A deployment should be reproducible from the content hash, not from an untracked local file.

More reference detail

The generated OpenAPI surface is available from a running instance at /api/openapi.json. Use it to generate a client for your language or to inspect the exact request and response contracts for the version you operate.