Rubrkit API documentation
This OpenAPI file is the canonical REST API contract for Rubrkit. The public website docs and MCP documentation resources should be generated from or backed by this source.
Canonical source
docs/api/openapi.yamldocs/api/README.mdTwo bearer-token modes, one authorization boundary.
Browser clients use short-lived login tokens. Scripts, MCP clients, CLI clients, and integrations use user-created Rubrkit API keys with scopes.
Login-token auth
Short-lived login token issued by the configured auth provider.
Use this mode for signed-in browser sessions and first-party clients. The token is verified by Rubrkit before mapping the identity to a Neon-backed user.
Header
Authorization: Bearer <short_lived_auth_token>API-key auth
Rubrkit API key created from the user dashboard.
Use this mode for scripts, integrations, MCP clients, CLIs, and SDK calls. API keys are named, scoped, revocable, and shown only once.
Header
Authorization: Bearer <rubrkit_api_key>API-key capabilities are explicit.
The scope list is read from the canonical OpenAPI contract and Markdown guide files in docs/api.
Artifact-bundle workflows stay API-first.
The endpoint groups below come directly from OpenAPI tags, so implemented routes and public docs stay aligned.
Auth, credits, async work, and proof are documented in Markdown.
These excerpts come from docs/api/README.md and cover the core concepts API users need before calling endpoints.
Failures use stable, safe codes.
Every public error response carries a machine-readable code, human message, and request identifier where available.
Error response
{
"error": {
"code": "unauthorized",
"message": "The request is valid.",
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"details": [
{}
]
}
}Canonical docs/api guide
This section renders Markdown files from docs/api. Add future guides there and the public page can render them without a duplicate source.
Rubrkit API Docs
docs/api/README.md
Rubrkit API Docs
docs/api/README.md
Rubrkit API Docs
These files are the canonical source for Rubrkit's public API documentation.
The same source should feed:
- Public website docs.
- MCP documentation search/read resources.
- Internal implementation reviews for
/api/v1.
Source Files
openapi.yaml: canonical REST API contract.- Markdown guides in this folder: concepts, authentication, credits, limits, errors, uploads, versioning, and examples.
Do not maintain separate copies of API docs for the website and MCP service. Generate or render both from this directory.
Validate the OpenAPI YAML contract with:
npm run api:validateAPI Design Rules
- All public routes live under
/api/v1. - Browser clients authenticate with short-lived auth-provider tokens.
- External clients authenticate with Rubrkit API keys.
- API keys are created, named, scoped, and revoked from the user dashboard.
- Every route enforces authorization, limits, and credit checks on the server.
- Every response includes a stable JSON shape.
- Every error includes a safe machine-readable code.
- Expensive operations should return enough metadata for users to understand credit cost and usage.
- Long-running operations should create async jobs and return a
jobIdquickly. - Job status and progress should be available through
/api/v1/jobs/{jobId}and job event endpoints.
Authentication
Rubrkit supports two bearer-token authentication modes:
Authorization: Bearer <short_lived_auth_token>Use this for signed-in browser sessions and first-party clients.
Firebase Auth is identity-only for browser sessions. Rubrkit accepts verified Firebase ID tokens from Google and GitHub sign-in by default. Microsoft can be enabled by adding microsoft.com to the server-side allowed provider list after the provider is configured in Firebase. Email/password, email-link, magic-link, passwordless-email, anonymous, and other unsupported Firebase providers are not accepted for durable Rubrkit API access.
Authorization: Bearer <rubrkit_api_key>Use this for scripts, integrations, MCP clients, and external API consumers.
API keys should be shown once, stored only as hashes, and displayed later only by name, prefix, scopes, creation time, last-used time, and status.
Initial Scopes
artifact_bundles:readartifact_bundles:writefiles:readfiles:writeaudits:runjobs:readjobs:writerubr_flow:convertevals:runexports:readexports:writeartifacts:pullcredits:read
Artifact Bundle Resource
In v1, /api/v1/artifact-bundles is the stable API path for Rubrkit artifact bundles.
An artifact bundle is one artifact-under-review plus its related files, such as a skill with SKILL.md, references, examples, tests, generated improvements, and proof reports. It is not a generic team/project workspace and it is not a single-file artifact model.
When files are uploaded, Rubrkit should infer the main artifact from high-confidence filenames such as SKILL.md, AGENTS.md, README.md, prompt.md, system.md, instructions.md, workflow.md, and rubr_flow files. Main artifact selection is backend-owned; clients cannot set isPrimary on upload or patch primaryFileId later as an override. If no confident main artifact exists, the bundle should remain without a main artifact marker and downstream audit/conversion flows should use bundle-level mode instead of silently choosing the first file.
Files can be removed from the active artifact bundle with DELETE /api/v1/artifact-bundles/{artifactBundleId}/files/{fileId}. This is a soft delete: current lists, reads, audits, and conversions stop seeing the file, while historical version metadata and stored snapshots remain available for provenance. The original path becomes reusable for a later upload. API-key callers must include files:write.
Keep artifactBundleId, artifact_bundles:read, and artifact_bundles:write stable for v1 clients. Public docs and UI copy should explain the product object as an artifact bundle.
The artifacts:pull API-key scope is accepted as a narrow read scope for CLI pull workflows. It can list and read artifact bundles, artifact-bundle version metadata, files, and file versions needed to sync local files. It does not grant write access, audit/eval/proof history reads, or expensive run permissions.
Async Jobs
Long-running artifact bundle work should create a background_jobs record and return a job ID quickly. Clients can poll GET /api/v1/jobs/{jobId} for the latest state and GET /api/v1/jobs/{jobId}/events for append-only progress events. Login-token callers can read and cancel their own jobs. API-key callers must include jobs:read for polling and jobs:write for POST /api/v1/jobs/{jobId}/cancel.
Job status responses include the state, phase, percent estimate, latest message, timestamps, artifact bundle/resource IDs, attempts, safe result metadata, and a safe error code/message when a job fails or pauses. Job state is stored in Postgres for v1; Firebase Realtime Database is not used for progress.
Audits
Audit runs belong to artifact bundles. POST /api/v1/artifact-bundles/{artifactBundleId}/audits/estimate returns the estimated audit credits for the same target-selection payload accepted by audit creation. API-key callers must include audits:run.
POST /api/v1/artifact-bundles/{artifactBundleId}/audits computes the same estimate, creates a persisted audit_runs record, creates an async audit job, checks credits/limits/circuit breaker before scoring starts, and returns 202 Accepted with a jobId plus the estimate. When RUBRKIT_AI_ENABLED is false, the route preserves the server-side mock scorer behavior. When AI is enabled, audit scoring runs through the Vercel AI SDK and records provider/model/tier/reasoning metadata in ai_runs. Clients should poll GET /api/v1/jobs/{jobId} until the job reaches a terminal state, then refresh the audit run or audit history.
By default an audit targets the current artifact bundle state: the backend-detected main artifact plus supporting files as context. If no main artifact is set, the audit uses bundle-level mode and treats all current files as the artifact under review. Callers can instead pass targetFileId with targetVersionNumber, or artifactBundleVersionNumber, to audit a selected file/version event. API-key callers must include audits:run to start an audit. Listing and reading audit history uses artifact_bundles:read.
Audit estimates use approximate token counts and product credit multipliers, not exact OpenAI pricing. The estimate includes estimated credits, estimated input/output tokens, file count, approximate character count, rubric count, selected model tier, reasoning effort, multipliers, and a breakdown. The estimate is persisted on the audit summary and usage-event metadata.
GET /api/v1/artifact-bundles/{artifactBundleId}/audits returns persisted audit history in newest-first order. GET /api/v1/artifact-bundles/{artifactBundleId}/audits/{auditRunId} returns one audit run, including stored scores, top findings, improved version, eval kit, target version IDs, safe errors, result metadata, estimated credit cost, and any actual provider usage/reconciliation summary. AI run traces are server-side metadata for proof-report and provenance services; they are not exposed as raw provider responses by the audit API.
rubr_flow Conversions
POST /api/v1/artifact-bundles/{artifactBundleId}/rubr-flow/conversions creates a persisted conversion record and async rubr_flow_conversion job. API-key callers must include rubr_flow:convert. By default the conversion targets the backend-detected main artifact and uses supporting files as context. If no main artifact exists, the conversion uses bundle-level mode and treats the current file set as the source. Callers can pass targetFileId with targetVersionNumber, or artifactBundleVersionNumber, using the same target-selection semantics as audits.
The conversion job progresses through analysis, mapping, generation, validation, repair, and saving phases. The generated rubr_flow is validated with validateRubrFlow; validation errors trigger a repair attempt before saving. If output still cannot be repaired, the conversion is marked failed with actionable validation issues in the report instead of silently accepting invalid rubr_flow.
Successful conversions save an editable generated file back into the same artifact bundle. The default path is generated/rubr_flow.rubr_flow; repeated conversions append new versions to that file with source rubr_flow_conversion. Conversion reports include source summary, block mapping, missing requirements, validation results, repair details, output file/version IDs, suggested evals, remaining risks, and estimated credit cost.
GET /api/v1/artifact-bundles/{artifactBundleId}/rubr-flow/conversions lists conversion history in newest-first order. GET /api/v1/artifact-bundles/{artifactBundleId}/rubr-flow/conversions/{conversionId} returns one conversion report. API-key callers must include artifact_bundles:read for history reads.
Evals And Proof Reports
POST /api/v1/artifact-bundles/{artifactBundleId}/evals creates a persisted eval run and async eval job. API-key callers must include evals:run. Evals compare immutable file versions from the same artifact bundle: callers can pass sourceFileVersionId and candidateFileVersionId, or sourceFileId/sourceVersionNumber and candidateFileId/candidateVersionNumber. When selectors are omitted, Rubrkit compares version 1 and the latest version of the backend-inferred main artifact; if no main artifact exists, callers must provide explicit file selectors.
Eval jobs generate or normalize test cases, run original-vs-candidate checks, and store observed source behavior, observed candidate behavior, pass/fail, score delta, diff metadata, evaluator version, rubric version, model/provider/config metadata, AI metadata, credit metadata, and known limitations. Failed cases are stored as evidence rather than discarded. If the job itself fails after admission, the failed run still stores safe error evidence for later inspection.
GET /api/v1/artifact-bundles/{artifactBundleId}/evals lists eval history in newest-first order, and GET /api/v1/artifact-bundles/{artifactBundleId}/evals/{evalRunId} returns one eval run. API-key callers must include artifact_bundles:read for history reads.
POST /api/v1/artifact-bundles/{artifactBundleId}/proof-reports creates a persisted proof-report record and async proof_report job. API-key callers must include evals:run. A proof report can reference an evalRunId and optionally an auditRunId, or it can receive the same source/candidate version selectors accepted by eval creation. Completed proof reports tie back to immutable source and candidate hashes and include test cases, expected behavior, observed behavior, pass/fail results, score delta, diff, evaluator version, rubric version, model/provider/config metadata, AI metadata, credit metadata, and known limitations.
Proof reports attempt to write a JSON export to Vercel Blob and persist export metadata on the report. If Blob export storage is unavailable, the report evidence remains in Postgres with an export failure note. GET /api/v1/artifact-bundles/{artifactBundleId}/proof-reports/{proofReportId} returns the stored report. API-key callers must include artifact_bundles:read.
Credits, Limits, And AI Pauses
GET /api/v1/credits returns the authenticated user's ledger-derived balance, account totals, recent ledger events, configured free grant values, and configured limit values. Login-token callers can read their own credits. API-key callers must include credits:read.
Credit ledger events are immutable. Grants and refunds add positive amounts; debits subtract credits; balances are derived from ledger events. Expensive AI work must pass authorization, API-key/user/artifact bundle limits, credit debit checks, and the global AI circuit breaker before any model provider call starts.
Audit credits default to dynamic estimation through RUBRKIT_AUDIT_CREDIT_MODE=dynamic. flat mode uses RUBRKIT_AUDIT_RUN_CREDITS as an explicit override/fallback for audits, and free mode records audits and rubr_flow conversions with zero charged credits while preserving the dynamic estimate for reporting. When AI-backed runs have related ai_runs provider usage and automatic reconciliation is enabled, Rubrkit can refund lower actual usage idempotently. Higher-than-estimated actual usage is recorded for calibration in v1 and is not surprise-charged after the run.
Credit and limit failures use distinct safe error codes:
credit_limit_exceeded: the user does not have enough credits for the requested expensive action.usage_limit_exceeded: a configured per-user or per-artifact-bundle AI usage cap would be exceeded.rate_limit_exceeded: a configured request limit was reached. Authenticated API request limits can apply by authenticated user, artifact bundle, and API key. Public-route IP throttles use trusted proxy fingerprints only when proxy headers are explicitly trusted.ai_circuit_breaker_open: new AI work is paused by environment override, database setting, or global budget threshold. Non-AI reads and editing routes should continue to work.
CLI And Artifact Pulls
Rubrkit should expose enough public API for the CLI package to pull approved artifacts into local projects.
Expected CLI entry point:
npx rubrkit pull [all|<artifact-bundle-or-artifact-selector>]CLI usage should authenticate with a Rubrkit API key, preferably scoped to artifacts:pull. Postinstall use must be opt-in from the consuming project and non-interactive.
The v1 CLI lives in this app repo under tools/rubrkit-cli while package ownership and publishing stay manual. The intended npm package name and executable are both rubrkit, so the public command shape remains:
npx rubrkit pull all --yesThe Rubrkit package itself must not sync artifacts during its own install lifecycle. Consuming projects can opt in explicitly:
{
"scripts": {
"postinstall": "rubrkit pull all --yes"
}
}Postinstall and CI usage should set RUBRKIT_API_KEY, or pass --api-key through a secret manager, and should use --yes with an unambiguous selector such as all, --artifact-bundle, or --artifact.
SDK And Artifact Testing
Rubrkit should expose artifact testing through the CLI and a JavaScript/TypeScript SDK.
Expected CLI commands:
npx rubrkit validate <path>
npx rubrkit test <path|selector>
npx rubrkit audit <path|selector>
npx rubrkit eval <path|selector>Local validation can run without an API key when it only uses static checks such as rubr_flow syntax validation. Remote AI-backed tests, audits, evals, and proof reports should authenticate with a Rubrkit API key and use async /api/v1 jobs. API keys for remote local-file testing should include the existing scopes needed for the composed workflow: artifact_bundles:write, files:write, audits:run, jobs:read, and credits:read.
The SDK should wrap the public /api/v1 contract rather than private server modules.
The v1 CLI and SDK implementation lives with the existing local package under tools/rubrkit-cli. Publishing and the final SDK package name still require owner approval; the current package exports the Rubrkit SDK class from rubrkit while keeping the executable as rubrkit.
Initial CLI output formats are text, json, and junit. JSON output is machine-readable and does not include progress prose. SARIF remains a later integration unless launch requirements change.
Remote SDK and CLI test runs compose the existing artifact-bundle APIs instead of using a standalone test-admission route. For a local file target, the client creates or selects an artifact bundle, uploads text files through POST /api/v1/artifact-bundles/{artifactBundleId}/files, starts an audit through POST /api/v1/artifact-bundles/{artifactBundleId}/audits, and polls GET /api/v1/jobs/{jobId}. Remote dry-runs do not call the API or require an API key.
CLI exit codes:
0: checks passed.1: checks completed and failed validation or quality gates.2: invalid CLI usage or invalid config.3: authentication or authorization failure.4: credit, usage-limit, or circuit-breaker block.5: network, provider, or server failure.
Email, Newsletter, And Notifications
Visitors can explicitly opt in to the marketing newsletter with:
POST /api/v1/newsletter/subscriptionsThe request must include consent: true. Rubrkit does not subscribe users automatically when accounts are created, and public newsletter responses are duplicate-safe so callers cannot discover whether an email belongs to an existing user or subscription.
Newsletter unsubscribe requests by email use:
POST /api/v1/newsletter/unsubscribeThat route returns a non-enumerating accepted response but does not directly mutate subscription state. Optional email unsubscribe links use hashed server-side tokens through:
POST /api/v1/email/unsubscribe-tokens/{token}/consumeOnly token hashes are stored after token creation. Raw unsubscribe tokens appear only in outbound optional-email links.
Signed-in users can read and patch optional notification categories with:
GET /api/v1/me/email-preferences
PATCH /api/v1/me/email-preferencesOptional categories default off until explicitly enabled or, for the marketing newsletter, explicitly subscribed. Must-receive categories are narrow and not user-disableable: account security, critical service/account notices, future billing/payment/credit purchase notices, and required legal/terms/privacy notices.
Local development and tests default to RUBRKIT_EMAIL_SEND_ENABLED=false and the outbox provider. Do not enable real provider sending without a verified provider, sender domain, production from/reply-to, and final marketing footer details.
MCP Docs
Rubrkit exposes a public MCP endpoint inside the same Next.js deployment:
POST /api/v1/mcpThe endpoint accepts JSON-RPC MCP requests over HTTP. Clients should send Content-Type: application/json and can send Accept: application/json, text/event-stream. Rubrkit currently returns JSON responses and supports protocol versions 2025-03-26 and 2025-06-18.
Example initialization request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {
"name": "example-client",
"version": "1.0.0"
}
}
}Docs tools and resources are public and backed by this directory:
- Search API docs.
- Read API docs by slug/path.
- Read the OpenAPI contract.
Product tools require the same bearer authentication as REST:
Authorization: Bearer <rubrkit_api_key>or:
Authorization: Bearer <short_lived_auth_token>MCP tools that perform product actions call the same service/controller layer as /api/v1 routes and apply the same scopes, auth, rate limits, ownership checks, credit checks, and async job behavior. Tool errors preserve the REST response envelope inside the MCP tools/call result with isError: true.
Initial MCP product tools cover:
- Create, list, and read artifact bundles.
- Upload, list, read, and update files.
- Start audits and poll jobs.
- Convert to
rubr_flowand poll jobs. - List and restore artifact bundle or file versions.
- Run evals and poll jobs.
- Export proof reports and poll jobs.
OpenAPI operations with generated examples.
Each request and response example is generated from the operation's OpenAPI schema. The contract remains the canonical source.
Auth
Session identity and authenticated user metadata.
GET/meGet the authenticated Rubrkit user.
/meGet the authenticated Rubrkit user.
Verifies a short-lived Firebase Auth bearer token or Rubrkit API key and returns the authenticated user profile. Login-token responses include provider identity metadata. API-key responses include display-safe key metadata only; raw keys and key hashes are never returned.
Example request
curl -X GET "https://rubrkit.com/api/v1/me" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"user": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"email": "api-user@rubrkit.dev",
"status": "active",
"planKey": "example_planKey",
"displayName": "Onboarding instruction bundle",
"avatarUrl": "https://rubrkit.com/api/v1",
"emailVerifiedAt": "2026-06-15T12:00:00.000Z",
"lastSeenAt": "2026-06-15T12:00:00.000Z",
"createdAt": "2026-06-15T12:00:00.000Z",
"updatedAt": "2026-06-15T12:00:00.000Z"
},
"identities": [
{
"provider": "firebase",
"providerUserId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"signInProvider": "google.com",
"signInProviderLabel": "example_signInProviderLabel",
"emailVerified": true,
"email": "api-user@rubrkit.dev",
"lastAuthenticatedAt": "2026-06-15T12:00:00.000Z"
}
],
"apiKey": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"name": "Onboarding instruction bundle",
"prefix": "rubrkit_live_prefix_example",
"scopes": [
"artifact_bundles:read"
],
"status": "active",
"lastUsedAt": "2026-06-15T12:00:00.000Z",
"expiresAt": "2026-06-15T12:00:00.000Z",
"revokedAt": "2026-06-15T12:00:00.000Z",
"createdAt": "2026-06-15T12:00:00.000Z",
"updatedAt": "2026-06-15T12:00:00.000Z"
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}Newsletter signup, notification preferences, and unsubscribe flows.
GET/me/email-preferencesGet authenticated user email preferences.
/me/email-preferencesGet authenticated user email preferences.
Returns optional email categories that the signed-in user can enable or disable, plus narrow must-receive account categories that are clearly labeled and cannot be disabled. Marketing newsletter emails remain explicit opt-in and users are not subscribed automatically by account creation.
Example request
curl -X GET "https://rubrkit.com/api/v1/me/email-preferences" \
-H "Authorization: Bearer <short_lived_auth_token>"Example response 200
{
"data": {
"optional": [
{
"key": "marketing_newsletter",
"label": "example_label",
"description": "example_description",
"enabled": true,
"canDisable": true,
"updatedAt": "2026-06-15T12:00:00.000Z"
}
],
"mustReceive": [
{
"key": "marketing_newsletter",
"label": "example_label",
"description": "example_description",
"enabled": true,
"canDisable": true,
"updatedAt": "2026-06-15T12:00:00.000Z"
}
]
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}PATCH/me/email-preferencesUpdate optional email preferences.
/me/email-preferencesUpdate optional email preferences.
Updates one or more optional email categories for the signed-in user. Must-receive categories cannot be patched and return a validation error.
Example request
curl -X PATCH "https://rubrkit.com/api/v1/me/email-preferences" \
-H "Authorization: Bearer <short_lived_auth_token>" \
-H "Content-Type: application/json" \
--data '{
"preferences": [
{
"category": "marketing_newsletter",
"enabled": true
}
]
}'Example response 200
{
"data": {
"optional": [
{
"key": "marketing_newsletter",
"label": "example_label",
"description": "example_description",
"enabled": true,
"canDisable": true,
"updatedAt": "2026-06-15T12:00:00.000Z"
}
],
"mustReceive": [
{
"key": "marketing_newsletter",
"label": "example_label",
"description": "example_description",
"enabled": true,
"canDisable": true,
"updatedAt": "2026-06-15T12:00:00.000Z"
}
]
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/newsletter/subscriptionsSubscribe to the marketing newsletter.
/newsletter/subscriptionsSubscribe to the marketing newsletter.
Accepts an explicit marketing newsletter opt-in from a visitor or user. The response is duplicate-safe and does not reveal whether the address belongs to an existing user or existing newsletter subscription.
Example request
curl -X POST "https://rubrkit.com/api/v1/newsletter/subscriptions" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{
"email": "api-user@rubrkit.dev",
"consent": true
}'Example response 200
{
"data": {
"accepted": true,
"message": "The request is valid."
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/newsletter/unsubscribeAccept a newsletter unsubscribe request.
/newsletter/unsubscribeAccept a newsletter unsubscribe request.
Accepts an email address and returns the same safe response whether or not a matching newsletter subscription exists. This endpoint does not directly unsubscribe the address; one-click unsubscribe links use signed server-side tokens through `/email/unsubscribe-tokens/{token}/consume`.
Example request
curl -X POST "https://rubrkit.com/api/v1/newsletter/unsubscribe" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{
"email": "api-user@rubrkit.dev"
}'Example response 200
{
"data": {
"accepted": true,
"message": "The request is valid."
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/email/unsubscribe-tokens/{token}/consumeConsume an unsubscribe token.
/email/unsubscribe-tokens/{token}/consumeConsume an unsubscribe token.
Consumes a one-click unsubscribe token for optional email categories. Rubrkit stores only token hashes after creation; raw tokens are never persisted. Must-receive categories do not issue unsubscribe tokens.
Parameters
Example request
curl -X POST "https://rubrkit.com/api/v1/email/unsubscribe-tokens/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/consume" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"accepted": true,
"category": "marketing_newsletter",
"message": "The request is valid."
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}API Keys
Dashboard-managed programmatic access keys.
GET/api-keysList dashboard-managed API keys.
/api-keysList dashboard-managed API keys.
Lists API keys owned by the signed-in user. Raw API key values and key hashes are never returned by this endpoint.
Example request
curl -X GET "https://rubrkit.com/api/v1/api-keys" \
-H "Authorization: Bearer <short_lived_auth_token>"Example response 200
{
"data": {
"apiKeys": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"name": "Onboarding instruction bundle",
"prefix": "rubrkit_live_prefix_example",
"scopes": [
"artifact_bundles:read"
],
"status": "active",
"lastUsedAt": "2026-06-15T12:00:00.000Z",
"expiresAt": "2026-06-15T12:00:00.000Z",
"revokedAt": "2026-06-15T12:00:00.000Z",
"createdAt": "2026-06-15T12:00:00.000Z",
"updatedAt": "2026-06-15T12:00:00.000Z"
}
]
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/api-keysCreate an API key.
/api-keysCreate an API key.
Creates a named API key for the signed-in user. The raw API key is returned exactly once in this response and is never stored by Rubrkit.
Example request
curl -X POST "https://rubrkit.com/api/v1/api-keys" \
-H "Authorization: Bearer <short_lived_auth_token>" \
-H "Content-Type: application/json" \
--data '{
"name": "Onboarding instruction bundle",
"scopes": [
"artifact_bundles:read"
]
}'Example response 201
{
"data": {
"apiKey": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"name": "Onboarding instruction bundle",
"prefix": "rubrkit_live_prefix_example",
"scopes": [
"artifact_bundles:read"
],
"status": "active",
"lastUsedAt": "2026-06-15T12:00:00.000Z",
"expiresAt": "2026-06-15T12:00:00.000Z",
"revokedAt": "2026-06-15T12:00:00.000Z",
"createdAt": "2026-06-15T12:00:00.000Z",
"updatedAt": "2026-06-15T12:00:00.000Z"
},
"rawApiKey": "<raw_rubrkit_api_key_shown_once>"
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}DELETE/api-keys/{keyId}Revoke an API key.
/api-keys/{keyId}Revoke an API key.
Revokes an API key owned by the signed-in user. Revoked keys cannot authenticate, and historical audit records keep their API key reference.
Parameters
Example request
curl -X DELETE "https://rubrkit.com/api/v1/api-keys/api_key_123" \
-H "Authorization: Bearer <short_lived_auth_token>"Example response 200
{
"data": {
"apiKey": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"name": "Onboarding instruction bundle",
"prefix": "rubrkit_live_prefix_example",
"scopes": [
"artifact_bundles:read"
],
"status": "active",
"lastUsedAt": "2026-06-15T12:00:00.000Z",
"expiresAt": "2026-06-15T12:00:00.000Z",
"revokedAt": "2026-06-15T12:00:00.000Z",
"createdAt": "2026-06-15T12:00:00.000Z",
"updatedAt": "2026-06-15T12:00:00.000Z"
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}Artifact Bundles
Artifact bundles. In v1, an artifact bundle is one artifact-under-review plus related references, examples, tests, generated files, and version history.
GET/artifact-bundlesList artifact bundles.
/artifact-bundlesList artifact bundles.
Lists artifact bundles owned by the authenticated user. In v1, an artifact bundle is one artifact-under-review plus related files. API-key callers must include `artifact_bundles:read` or `artifacts:pull`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"artifactBundles": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"name": "Onboarding instruction bundle",
"status": "active",
"activeVersionNumber": 0,
"customRubric": {},
"settings": {},
"primaryFile": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "example_artifactType",
"status": "example_status",
"isPrimary": true,
"sizeBytes": 1,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 1,
"metadata": "example_metadata"
},
"fileCount": 0,
"versionCount": 0,
"latestVersion": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleVersionNumber": 1,
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"filePath": "prompts/main.md",
"fileVersionNumber": 1,
"source": "example_source",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 1,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
}
],
"pagination": {
"limit": 1,
"nextCursor": "example_nextCursor"
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/artifact-bundlesCreate an artifact bundle.
/artifact-bundlesCreate an artifact bundle.
Creates an owner-scoped artifact bundle for one skill, agent, prompt, command, workflow, or rubr_flow package under review. API-key callers must include `artifact_bundles:write`.
Example request
curl -X POST "https://rubrkit.com/api/v1/artifact-bundles" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{
"name": "Onboarding instruction bundle"
}'Example response 201
{
"data": {
"artifactBundle": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"name": "Onboarding instruction bundle",
"status": "active",
"activeVersionNumber": 0,
"customRubric": {},
"settings": {},
"primaryFile": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "example_mediaType",
"detectedLanguage": "example_detectedLanguage",
"storageProvider": "example_storageProvider"
}
},
"fileCount": 0,
"versionCount": 0,
"latestVersion": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleVersionNumber": 1,
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"filePath": "prompts/main.md",
"fileVersionNumber": 1,
"source": "upload",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 0,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}GET/artifact-bundles/{artifactBundleId}Get an artifact bundle.
/artifact-bundles/{artifactBundleId}Get an artifact bundle.
Returns artifact bundle metadata, files, and code-editor-style file tree for an artifact bundle owned by the authenticated user. API-key callers must include `artifact_bundles:read` or `artifacts:pull`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"artifactBundle": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"name": "Onboarding instruction bundle",
"status": "active",
"activeVersionNumber": 0,
"customRubric": {},
"settings": {},
"primaryFile": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "example_mediaType",
"detectedLanguage": "example_detectedLanguage",
"storageProvider": "example_storageProvider"
}
},
"fileCount": 0,
"versionCount": 0,
"latestVersion": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleVersionNumber": 1,
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"filePath": "prompts/main.md",
"fileVersionNumber": 1,
"source": "upload",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 0,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
},
"files": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "text/markdown",
"detectedLanguage": "markdown",
"storageProvider": "vercel_blob"
}
}
],
"tree": {
"type": "folder",
"name": "Onboarding instruction bundle",
"path": "prompts/main.md",
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactType": "prompt",
"status": "original",
"language": "example_language",
"isPrimary": true,
"sizeBytes": 0
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}PATCH/artifact-bundles/{artifactBundleId}Update an artifact bundle.
/artifact-bundles/{artifactBundleId}Update an artifact bundle.
Updates artifact bundle metadata. Main artifact detection is backend-owned and cannot be assigned by clients. API-key callers must include `artifact_bundles:write`. Archived artifact bundles are not writable.
Parameters
Example request
curl -X PATCH "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{
"name": "Onboarding instruction bundle"
}'Example response 200
{
"data": {
"artifactBundle": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"name": "Onboarding instruction bundle",
"status": "active",
"activeVersionNumber": 0,
"customRubric": {},
"settings": {},
"primaryFile": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "example_mediaType",
"detectedLanguage": "example_detectedLanguage",
"storageProvider": "example_storageProvider"
}
},
"fileCount": 0,
"versionCount": 0,
"latestVersion": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleVersionNumber": 1,
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"filePath": "prompts/main.md",
"fileVersionNumber": 1,
"source": "upload",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 0,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
},
"files": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "text/markdown",
"detectedLanguage": "markdown",
"storageProvider": "vercel_blob"
}
}
],
"tree": {
"type": "folder",
"name": "Onboarding instruction bundle",
"path": "prompts/main.md",
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactType": "prompt",
"status": "original",
"language": "example_language",
"isPrimary": true,
"sizeBytes": 0
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}DELETE/artifact-bundles/{artifactBundleId}Archive an artifact bundle.
/artifact-bundles/{artifactBundleId}Archive an artifact bundle.
Soft-archives an artifact bundle owned by the authenticated user. Historical files and versions remain in Postgres/Blob storage. API-key callers must include `artifact_bundles:write`.
Parameters
Example request
curl -X DELETE "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"artifactBundle": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"name": "Onboarding instruction bundle",
"status": "active",
"activeVersionNumber": 0,
"customRubric": {},
"settings": {},
"primaryFile": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "example_mediaType",
"detectedLanguage": "example_detectedLanguage",
"storageProvider": "example_storageProvider"
}
},
"fileCount": 0,
"versionCount": 0,
"latestVersion": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleVersionNumber": 1,
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"filePath": "prompts/main.md",
"fileVersionNumber": 1,
"source": "upload",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 0,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}Files
Artifact-bundle file upload, reading, editing, and metadata.
GET/artifact-bundles/{artifactBundleId}/filesList files in an artifact bundle.
/artifact-bundles/{artifactBundleId}/filesList files in an artifact bundle.
Lists text artifact file metadata and a code-editor-style file tree for an artifact bundle owned by the authenticated user. API-key callers must include `files:read` or `artifacts:pull`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/files" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"files": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "text/markdown",
"detectedLanguage": "markdown",
"storageProvider": "vercel_blob"
}
}
],
"tree": {
"type": "folder",
"name": "Onboarding instruction bundle",
"path": "prompts/main.md",
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactType": "prompt",
"status": "original",
"language": "example_language",
"isPrimary": true,
"sizeBytes": 0
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/artifact-bundles/{artifactBundleId}/filesUpload text files to an artifact bundle.
/artifact-bundles/{artifactBundleId}/filesUpload text files to an artifact bundle.
Uploads one or more text files into an existing artifact bundle. Each uploaded file is stored as immutable version 1 in Vercel Blob, while metadata, ownership, byte size, content hash, media type, detected language, and version relationships are stored in Postgres. API-key callers must include `files:write`.
Parameters
Example request
curl -X POST "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/files" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{
"files": [
{
"path": "prompts/main.md",
"content": "TASK \"Improve onboarding instructions\"\\nVERIFY\\n PASS WHEN the next action is clear"
}
]
}'Example response 201
{
"data": {
"files": [
{
"file": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "example_mediaType",
"detectedLanguage": "example_detectedLanguage",
"storageProvider": "example_storageProvider"
}
},
"version": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"versionNumber": 1,
"source": "upload",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 0,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"message": "The request is valid.",
"metadata": {
"mediaType": "example_mediaType",
"detectedLanguage": "example_detectedLanguage",
"storageProvider": "example_storageProvider"
}
}
}
]
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}GET/artifact-bundles/{artifactBundleId}/files/{fileId}Read the latest file version.
/artifact-bundles/{artifactBundleId}/files/{fileId}Read the latest file version.
Returns file metadata, latest version metadata, and text content through the authenticated API. API-key callers must include `files:read` or `artifacts:pull`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/files/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"file": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "text/markdown",
"detectedLanguage": "markdown",
"storageProvider": "vercel_blob"
}
},
"version": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"versionNumber": 1,
"source": "upload",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 0,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"message": "The request is valid.",
"metadata": {
"mediaType": "text/markdown",
"detectedLanguage": "markdown",
"storageProvider": "vercel_blob"
}
},
"content": "TASK \"Improve onboarding instructions\"\\nVERIFY\\n PASS WHEN the next action is clear"
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}PUT/artifact-bundles/{artifactBundleId}/files/{fileId}Edit a file by creating a new immutable version.
/artifact-bundles/{artifactBundleId}/files/{fileId}Edit a file by creating a new immutable version.
Stores the supplied text content as a new Blob snapshot and creates the next file version. Existing versions remain readable. API-key callers must include `files:write`.
Parameters
Example request
curl -X PUT "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/files/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{
"content": "TASK \"Improve onboarding instructions\"\\nVERIFY\\n PASS WHEN the next action is clear"
}'Example response 200
{
"data": {
"file": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "text/markdown",
"detectedLanguage": "markdown",
"storageProvider": "vercel_blob"
}
},
"version": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"versionNumber": 1,
"source": "upload",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 0,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"message": "The request is valid.",
"metadata": {
"mediaType": "text/markdown",
"detectedLanguage": "markdown",
"storageProvider": "vercel_blob"
}
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}DELETE/artifact-bundles/{artifactBundleId}/files/{fileId}Delete a file from the active artifact bundle.
/artifact-bundles/{artifactBundleId}/files/{fileId}Delete a file from the active artifact bundle.
Soft-deletes the file from the active artifact bundle view while keeping historical file-version records and stored snapshots for provenance. The original path becomes reusable for a future upload. API-key callers must include `files:write`.
Parameters
Example request
curl -X DELETE "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/files/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"file": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "text/markdown",
"detectedLanguage": "markdown",
"storageProvider": "vercel_blob"
}
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}Versions
Artifact-bundle and file version history.
GET/artifact-bundles/{artifactBundleId}/versionsList artifact bundle version events.
/artifact-bundles/{artifactBundleId}/versionsList artifact bundle version events.
Lists artifact bundle-level version events derived from owner-scoped file version metadata in newest-first order. API-key callers must include `artifact_bundles:read` or `artifacts:pull`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/versions" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"versions": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleVersionNumber": 1,
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"filePath": "prompts/main.md",
"fileVersionNumber": 1,
"source": "upload",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 0,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
]
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/artifact-bundles/{artifactBundleId}/restoreRestore an artifact bundle version.
/artifact-bundles/{artifactBundleId}/restoreRestore an artifact bundle version.
Restores files that existed at a prior artifact bundle version by creating new immutable restore versions through the Blob-backed snapshot layer. Files created after the target version are reported as skipped because v1 file deletion restore is not yet supported. API-key callers must include both `artifact_bundles:write` and `files:write`.
Parameters
Example request
curl -X POST "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/restore" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{
"versionNumber": 1
}'Example response 200
{
"data": {
"artifactBundle": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"name": "Onboarding instruction bundle",
"status": "active",
"activeVersionNumber": 0,
"customRubric": {},
"settings": {},
"primaryFile": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "example_mediaType",
"detectedLanguage": "example_detectedLanguage",
"storageProvider": "example_storageProvider"
}
},
"fileCount": 0,
"versionCount": 0,
"latestVersion": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleVersionNumber": 1,
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"filePath": "prompts/main.md",
"fileVersionNumber": 1,
"source": "upload",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 0,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
},
"restoredFiles": [
{
"file": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "example_mediaType",
"detectedLanguage": "example_detectedLanguage",
"storageProvider": "example_storageProvider"
}
},
"version": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"versionNumber": 1,
"source": "upload",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 0,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"message": "The request is valid.",
"metadata": {
"mediaType": "example_mediaType",
"detectedLanguage": "example_detectedLanguage",
"storageProvider": "example_storageProvider"
}
}
}
],
"skippedFiles": [
{
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"reason": "file_missing_or_deleted",
"path": "prompts/main.md"
}
],
"restoredFromArtifactBundleVersionNumber": 1
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}GET/artifact-bundles/{artifactBundleId}/files/{fileId}/versionsList file versions.
/artifact-bundles/{artifactBundleId}/files/{fileId}/versionsList file versions.
Lists immutable file versions in newest-first order. API-key callers must include `files:read` or `artifacts:pull`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/files/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/versions" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"versions": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"versionNumber": 1,
"source": "upload",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 0,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"message": "The request is valid.",
"metadata": {
"mediaType": "text/markdown",
"detectedLanguage": "markdown",
"storageProvider": "vercel_blob"
}
}
]
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}GET/artifact-bundles/{artifactBundleId}/files/{fileId}/versions/{versionNumber}Read a specific file version.
/artifact-bundles/{artifactBundleId}/files/{fileId}/versions/{versionNumber}Read a specific file version.
Returns immutable file-version metadata and text content. API-key callers must include `files:read` or `artifacts:pull`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/files/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/versions/1" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"version": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"versionNumber": 1,
"source": "upload",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 0,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"message": "The request is valid.",
"metadata": {
"mediaType": "text/markdown",
"detectedLanguage": "markdown",
"storageProvider": "vercel_blob"
}
},
"content": "TASK \"Improve onboarding instructions\"\\nVERIFY\\n PASS WHEN the next action is clear"
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/artifact-bundles/{artifactBundleId}/files/{fileId}/versions/{versionNumber}/restoreRestore a previous file version.
/artifact-bundles/{artifactBundleId}/files/{fileId}/versions/{versionNumber}/restoreRestore a previous file version.
Restores an older version by reading its immutable snapshot and creating a new latest version. History is never deleted or overwritten. API-key callers must include `files:write`.
Parameters
Example request
curl -X POST "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/files/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/versions/1/restore" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{}'Example response 200
{
"data": {
"file": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"path": "prompts/main.md",
"artifactType": "prompt",
"status": "original",
"isPrimary": true,
"sizeBytes": 0,
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"latestVersionNumber": 0,
"metadata": {
"mediaType": "text/markdown",
"detectedLanguage": "markdown",
"storageProvider": "vercel_blob"
}
},
"version": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"versionNumber": 1,
"source": "upload",
"contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"sizeBytes": 0,
"parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"message": "The request is valid.",
"metadata": {
"mediaType": "text/markdown",
"detectedLanguage": "markdown",
"storageProvider": "vercel_blob"
}
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}Audits
Rubric scoring, critique, and improvement runs.
GET/artifact-bundles/{artifactBundleId}/auditsList audit runs for an artifact bundle.
/artifact-bundles/{artifactBundleId}/auditsList audit runs for an artifact bundle.
Lists persisted audit runs for an artifact bundle owned by the authenticated user. API-key callers must include `artifact_bundles:read`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/audits" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"auditRuns": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"targetFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"requestedByApiKeyId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"status": "queued",
"rubricKey": "example_rubricKey",
"rubricVersion": "example_rubricVersion",
"artifactType": "prompt",
"summary": {}
}
],
"pagination": {
"limit": 1,
"nextCursor": "example_nextCursor"
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/artifact-bundles/{artifactBundleId}/auditsStart an audit run.
/artifact-bundles/{artifactBundleId}/auditsStart an audit run.
Creates a persisted audit run and an async audit job for the current artifact bundle state, a selected file version, or a selected artifact-bundle version event. Rubrkit computes an estimated credit cost from the selected bundle snapshot before debiting credits and returns that estimate with the `jobId`; clients poll `/jobs/{jobId}` for progress. API-key callers must include `audits:run`.
Parameters
Example request
curl -X POST "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/audits" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{}'Example response 202
{
"data": {
"auditRun": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"targetFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"requestedByApiKeyId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"status": "queued",
"rubricKey": "example_rubricKey",
"rubricVersion": "example_rubricVersion",
"artifactType": "prompt",
"summary": {}
},
"job": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"kind": "audit",
"state": "queued",
"phase": "preparing_context",
"percent": 0,
"message": "The request is valid.",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"resourceType": "example_resourceType",
"resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"attempts": 0
},
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"creditCost": {
"credits": 0,
"reason": "example_reason",
"estimate": true,
"mode": "dynamic",
"finalChargedCredits": 0
},
"estimate": {
"mode": "dynamic",
"estimatedCredits": 0,
"dynamicEstimatedCredits": 0,
"estimatedInputTokens": 0,
"estimatedOutputTokens": 0,
"estimatedTotalTokens": 0,
"weightedTokens": 0,
"fileCount": 0,
"totalCharacters": 0,
"rubricCount": 1
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/artifact-bundles/{artifactBundleId}/audits/estimateEstimate audit credits.
/artifact-bundles/{artifactBundleId}/audits/estimateEstimate audit credits.
Returns a dynamic audit credit estimate for the same target-selection fields accepted by audit creation. The estimate is based on the selected artifact-bundle snapshot, approximate token counts, file count, rubric count, model tier, and reasoning effort. API-key callers must include `audits:run`.
Parameters
Example request
curl -X POST "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/audits/estimate" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{}'Example response 200
{
"data": {
"estimate": {
"mode": "dynamic",
"estimatedCredits": 0,
"dynamicEstimatedCredits": 0,
"estimatedInputTokens": 0,
"estimatedOutputTokens": 0,
"estimatedTotalTokens": 0,
"weightedTokens": 0,
"fileCount": 0,
"totalCharacters": 0,
"rubricCount": 1
},
"creditCost": {
"credits": 0,
"reason": "example_reason",
"estimate": true,
"mode": "dynamic",
"finalChargedCredits": 0
},
"target": {
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"targetMode": "file",
"targetFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"targetFilePath": "prompts/main.md",
"targetFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"targetFileVersionNumber": 1,
"artifactBundleVersionNumber": 1,
"inputVersionIds": [
"018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
],
"inputHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}GET/artifact-bundles/{artifactBundleId}/audits/{auditRunId}Get an audit run.
/artifact-bundles/{artifactBundleId}/audits/{auditRunId}Get an audit run.
Returns a persisted audit run and its result for an artifact bundle owned by the authenticated user. API-key callers must include `artifact_bundles:read`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/audits/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"auditRun": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"targetFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"requestedByApiKeyId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"status": "queued",
"rubricKey": "example_rubricKey",
"rubricVersion": "example_rubricVersion",
"artifactType": "prompt",
"summary": {}
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}rubr_flow
rubr_flow conversion, validation, and certification.
GET/artifact-bundles/{artifactBundleId}/rubr-flow/conversionsList rubr_flow conversions for an artifact bundle.
/artifact-bundles/{artifactBundleId}/rubr-flow/conversionsList rubr_flow conversions for an artifact bundle.
Lists persisted rubr_flow conversion history for an artifact bundle owned by the authenticated user. API-key callers must include `artifact_bundles:read`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/rubr-flow/conversions" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"conversions": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"sourceFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"outputFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"outputFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"status": "queued",
"validatorVersion": "example_validatorVersion",
"sourceSummary": {},
"sourceMapping": {}
}
],
"pagination": {
"limit": 1,
"nextCursor": "example_nextCursor"
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/artifact-bundles/{artifactBundleId}/rubr-flow/conversionsStart a rubr_flow conversion.
/artifact-bundles/{artifactBundleId}/rubr-flow/conversionsStart a rubr_flow conversion.
Creates a persisted conversion record and async rubr_flow conversion job for the backend-detected main artifact, using supporting files as context, or for the full bundle when no main artifact is inferred. The generated rubr_flow is validated, repaired when possible, and saved back into the same artifact bundle as an editable generated file. API-key callers must include `rubr_flow:convert`.
Parameters
Example request
curl -X POST "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/rubr-flow/conversions" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{}'Example response 202
{
"data": {
"conversion": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"sourceFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"outputFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"outputFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"status": "queued",
"validatorVersion": "example_validatorVersion",
"sourceSummary": {},
"sourceMapping": {}
},
"job": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"kind": "audit",
"state": "queued",
"phase": "preparing_context",
"percent": 0,
"message": "The request is valid.",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"resourceType": "example_resourceType",
"resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"attempts": 0
},
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"creditCost": {
"credits": 0,
"reason": "example_reason",
"estimate": true,
"mode": "dynamic"
},
"estimate": {
"mode": "dynamic",
"estimatedCredits": 0,
"dynamicEstimatedCredits": 0,
"estimatedInputTokens": 0,
"estimatedOutputTokens": 0,
"estimatedTotalTokens": 0,
"weightedTokens": 0,
"fileCount": 0,
"totalCharacters": 0,
"modelTier": "cheap"
},
"target": {
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"targetMode": "file",
"targetFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"targetFilePath": "prompts/main.md",
"targetFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"targetFileVersionNumber": 1,
"artifactBundleVersionNumber": 1,
"inputVersionIds": [
"018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
],
"inputHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"outputPath": "prompts/main.md"
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}GET/artifact-bundles/{artifactBundleId}/rubr-flow/conversions/{conversionId}Get a rubr_flow conversion.
/artifact-bundles/{artifactBundleId}/rubr-flow/conversions/{conversionId}Get a rubr_flow conversion.
Returns a persisted rubr_flow conversion report, validation result, generated file references, and safe error metadata for an artifact bundle owned by the authenticated user. API-key callers must include `artifact_bundles:read`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/rubr-flow/conversions/1" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"conversion": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"sourceFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"outputFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"outputFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"status": "queued",
"validatorVersion": "example_validatorVersion",
"sourceSummary": {},
"sourceMapping": {}
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}Evals
Test cases, regression runs, and proof reports.
GET/artifact-bundles/{artifactBundleId}/evalsList eval runs for an artifact bundle.
/artifact-bundles/{artifactBundleId}/evalsList eval runs for an artifact bundle.
Lists persisted eval runs for an artifact bundle owned by the authenticated user. Failed cases and failed eval jobs remain stored as evidence. API-key callers must include `artifact_bundles:read`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/evals" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"evalRuns": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"auditRunId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"status": "queued",
"evaluatorVersion": "example_evaluatorVersion",
"scenarioCount": 0,
"passCount": 0,
"failCount": 0,
"cases": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"name": "Onboarding instruction bundle",
"type": "example_type",
"input": "example_input",
"expectedBehavior": "example_expectedBehavior",
"passCriteria": "example_passCriteria"
}
]
}
],
"pagination": {
"limit": 1,
"nextCursor": "example_nextCursor"
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/artifact-bundles/{artifactBundleId}/evalsStart an eval run.
/artifact-bundles/{artifactBundleId}/evalsStart an eval run.
Creates a persisted eval run and async eval job that compares immutable source and candidate file versions inside the same artifact bundle. When selectors are omitted, Rubrkit compares version 1 and the latest version of the backend-inferred main artifact, or requires explicit file selectors when no main artifact is inferred. API-key callers must include `evals:run`.
Parameters
Example request
curl -X POST "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/evals" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{}'Example response 202
{
"data": {
"evalRun": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"auditRunId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"status": "queued",
"evaluatorVersion": "example_evaluatorVersion",
"scenarioCount": 0,
"passCount": 0,
"failCount": 0,
"cases": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"name": "Onboarding instruction bundle",
"type": "scenario",
"input": "example_input",
"expectedBehavior": "example_expectedBehavior",
"passCriteria": "example_passCriteria"
}
]
},
"job": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"kind": "audit",
"state": "queued",
"phase": "preparing_context",
"percent": 0,
"message": "The request is valid.",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"resourceType": "example_resourceType",
"resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"attempts": 0
},
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"creditCost": {
"credits": 0,
"reason": "example_reason",
"estimate": true,
"mode": "dynamic"
},
"estimate": {
"mode": "dynamic",
"estimatedCredits": 0,
"dynamicEstimatedCredits": 0,
"estimatedInputTokens": 0,
"estimatedOutputTokens": 0,
"estimatedTotalTokens": 0,
"weightedTokens": 0,
"fileCount": 0,
"totalCharacters": 0,
"caseCount": 0
},
"target": {
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"sourceFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"sourceFilePath": "prompts/main.md",
"sourceFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"sourceFileVersionNumber": 1,
"sourceHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"candidateFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"candidateFilePath": "prompts/main.md",
"candidateFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"candidateFileVersionNumber": 1
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}GET/artifact-bundles/{artifactBundleId}/evals/{evalRunId}Get an eval run.
/artifact-bundles/{artifactBundleId}/evals/{evalRunId}Get an eval run.
Returns one persisted eval run, including test cases, observed behavior, pass/fail outcomes, score deltas, diff metadata, model/provider metadata, credit metadata, and safe error evidence. API-key callers must include `artifact_bundles:read`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/evals/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"evalRun": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"auditRunId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"status": "queued",
"evaluatorVersion": "example_evaluatorVersion",
"scenarioCount": 0,
"passCount": 0,
"failCount": 0,
"cases": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"name": "Onboarding instruction bundle",
"type": "scenario",
"input": "example_input",
"expectedBehavior": "example_expectedBehavior",
"passCriteria": "example_passCriteria"
}
]
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/artifact-bundles/{artifactBundleId}/proof-reportsStart a proof report.
/artifact-bundles/{artifactBundleId}/proof-reportsStart a proof report.
Creates a persisted proof-report record and async proof-report job for a source-vs-candidate comparison, optionally tied to an eval run and audit run. Completed reports attach immutable source/candidate hashes, eval evidence, AI metadata, credit metadata, known limitations, and Blob-backed export metadata when storage is available. API-key callers must include `evals:run`.
Parameters
Example request
curl -X POST "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/proof-reports" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{}'Example response 202
{
"data": {
"proofReport": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"auditRunId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"evalRunId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"sourceFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"candidateFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"status": "queued",
"reportVersion": "example_reportVersion",
"artifactHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
},
"job": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"kind": "audit",
"state": "queued",
"phase": "preparing_context",
"percent": 0,
"message": "The request is valid.",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"resourceType": "example_resourceType",
"resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"attempts": 0
},
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"creditCost": {
"credits": 0,
"reason": "example_reason",
"estimate": true,
"mode": "dynamic"
},
"estimate": {
"mode": "dynamic",
"estimatedCredits": 0,
"dynamicEstimatedCredits": 0,
"estimatedInputTokens": 0,
"estimatedOutputTokens": 0,
"estimatedTotalTokens": 0,
"weightedTokens": 0,
"fileCount": 0,
"totalCharacters": 0,
"caseCount": 0
},
"target": {
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"sourceFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"sourceFilePath": "prompts/main.md",
"sourceFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"sourceFileVersionNumber": 1,
"sourceHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
"candidateFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"candidateFilePath": "prompts/main.md",
"candidateFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"candidateFileVersionNumber": 1
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}GET/artifact-bundles/{artifactBundleId}/proof-reports/{proofReportId}Get a proof report.
/artifact-bundles/{artifactBundleId}/proof-reports/{proofReportId}Get a proof report.
Returns one persisted proof report with immutable version hashes, summary, evidence, model/provider/config metadata, credit metadata, export metadata, and safe error state. API-key callers must include `artifact_bundles:read`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/proof-reports/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"proofReport": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"auditRunId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"evalRunId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"sourceFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"candidateFileVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"status": "queued",
"reportVersion": "example_reportVersion",
"artifactHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}Credits
Credit balance, ledger events, and usage cost previews.
GET/creditsGet credit balance and recent ledger events.
/creditsGet credit balance and recent ledger events.
Returns the authenticated user's ledger-derived credit balance, account totals, recent immutable ledger events, configured free grants, and configured limit values. API-key callers must include the `credits:read` scope.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/credits" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"balance": 1,
"account": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"userId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"balance": 1,
"lifetimeGranted": 0,
"lifetimeUsed": 0,
"createdAt": "2026-06-15T12:00:00.000Z",
"updatedAt": "2026-06-15T12:00:00.000Z"
},
"ledgerEvents": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"type": "signup_grant",
"amount": 1,
"balanceAfter": 1,
"resourceType": "example_resourceType",
"resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"metadata": {},
"createdAt": "2026-06-15T12:00:00.000Z"
}
],
"freeGrants": {
"signupCredits": 0,
"monthlyCredits": 0
},
"limits": {
"userAiDailyCredits": 0,
"artifactBundleAiDailyCredits": 0,
"userApiRateLimitPerMinute": 0,
"artifactBundleApiRateLimitPerMinute": 0,
"apiKeyRateLimitPerMinute": 0
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}Jobs
Asynchronous job status and progress events for long-running work.
GET/jobs/{jobId}Get async job status.
/jobs/{jobId}Get async job status.
Returns polling-friendly status for a long-running job owned by the authenticated user. API-key callers must include `jobs:read`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/jobs/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"job": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"kind": "audit",
"state": "queued",
"phase": "preparing_context",
"percent": 0,
"message": "The request is valid.",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"resourceType": "example_resourceType",
"resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"attempts": 0
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}GET/jobs/{jobId}/eventsList async job progress events.
/jobs/{jobId}/eventsList async job progress events.
Lists append-only progress events for a long-running job owned by the authenticated user. Events are returned oldest first for timeline rendering. API-key callers must include `jobs:read`.
Parameters
Example request
curl -X GET "https://rubrkit.com/api/v1/jobs/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/events" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"events": [
{
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"state": "queued",
"phase": "example_phase",
"percent": 0,
"message": "The request is valid.",
"event": {},
"createdAt": "2026-06-15T12:00:00.000Z"
}
],
"pagination": {
"limit": 1,
"nextCursor": "example_nextCursor"
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}POST/jobs/{jobId}/cancelCancel an async job.
/jobs/{jobId}/cancelCancel an async job.
Marks a queued, running, waiting, or paused job as cancelled and appends a cancellation event. Completed and failed jobs cannot be cancelled. API-key callers must include `jobs:write`.
Parameters
Example request
curl -X POST "https://rubrkit.com/api/v1/jobs/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/cancel" \
-H "Authorization: Bearer <rubrkit_api_key>"Example response 200
{
"data": {
"job": {
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"kind": "audit",
"state": "queued",
"phase": "preparing_context",
"percent": 0,
"message": "The request is valid.",
"artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"resourceType": "example_resourceType",
"resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"attempts": 0
}
},
"requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}MCP
Model Context Protocol endpoint for docs resources and authenticated product tools.
OPTIONS/mcpMCP CORS preflight.
/mcpMCP CORS preflight.
Public unauthenticated CORS preflight for the Streamable HTTP MCP endpoint. This route does not perform product work and only returns allowed MCP headers/methods.
Example request
curl -X OPTIONS "https://rubrkit.com/api/v1/mcp" \
-H "Authorization: Bearer <short_lived_auth_token>"Example response 204
{
"data": null
}POST/mcpRubrkit MCP endpoint.
/mcpRubrkit MCP endpoint.
Public Streamable HTTP-style MCP JSON-RPC endpoint. Docs tools and docs resources read the canonical `docs/api` source files. Product tools call the same `/api/v1` controller/service capabilities as REST and enforce the same bearer authentication, API-key scopes, rate limits, ownership checks, credit checks, and async job behavior. MCP clients authenticate product tool calls with the same `Authorization: Bearer` login token or Rubrkit API key used by REST; public docs reads do not require authentication.
Parameters
Example request
curl -X POST "https://rubrkit.com/api/v1/mcp" \
-H "Authorization: Bearer <rubrkit_api_key>" \
-H "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"method": "initialize"
}'Example response 200
{
"jsonrpc": "2.0",
"id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
"result": {},
"error": {
"code": -32600,
"message": "The request is valid.",
"data": {}
}
}