rubrkit
Pricing
Sign In
API

Run the grading loop from your own code.

Grade instructions, manage artifact bundles, run audits and evals, and pull approved artifacts over one scoped, REST-over-JSON contract. Authenticate with an API key and call the exact operations the dashboard and CLI use.

Create API keysBrowse endpoints

API at a glance

Base URLhttps://www.rubrkit.com/api/v1
AuthBearer API key
FormatREST · JSON
SpecOpenAPI 3.1.0
48 operations
12 resources
13 scopes
How it works

Four things to know before your first call.

The API is small and predictable: one base URL, one auth model, and an explicit pattern for the long-running, credit-spending work.

REST over JSON

Every endpoint is a REST resource that speaks JSON over HTTPS at a single base URL. It is the same /api/v1 contract the web app and CLI use.

Scoped key auth

Authenticate with a bearer API key scoped to exactly the capabilities you grant it. No cookies, no sessions, and keys are revocable at any time.

Async jobs

Long-running work such as audits, rubr_flow conversions, and eval runs returns a job you poll for status and progress instead of holding the request open.

Credits and proof

Spending operations draw from a credit balance you can preview before running, and audits and evals produce a proof report you can read back later.

Authentication

Scoped API keys, one authorization boundary.

Scripts, CLIs, and integrations authenticate with named, scoped, revocable API keys. The key is shown only once when you create it.

API-key auth

Rubrkit API key created from the user dashboard.

Header
Authorization: Bearer <rubrkit_api_key>
01

Create a scoped key

In the dashboard, create an API key and grant only the scopes the integration needs. The secret is shown once, so store it immediately.

02

Send it as a bearer token

Authenticate every request with the Authorization: Bearer <rubrkit_api_key> header. There are no cookies or sessions to manage for programmatic access.

03

Stay inside your scopes

Each endpoint declares the scopes it requires. A key without them returns a forbidden error, and any key can be rotated or revoked from the dashboard at any time.

API key capabilities

Every scope grants one explicit capability.

Grant a key only the scopes its job needs. An endpoint that requires a scope the key does not hold returns a forbidden error.

artifact_bundles:read

Read artifact bundles and everything inside them.

artifact_bundles:write

Create artifact bundles and update their contents.

artifacts:pull

Pull approved artifacts into local clients such as the CLI.

audits:run

Start rubric scoring, critique, and improvement runs.

credits:read

Read the credit balance, ledger, and cost previews.

evals:run

Run eval test cases and regression suites.

exports:read

Read generated exports and proof reports.

exports:write

Generate exports and proof reports.

files:read

Read the individual files inside a bundle.

files:write

Upload, edit, and remove bundle files.

jobs:read

Poll the status and progress of asynchronous jobs.

jobs:write

Cancel or retry asynchronous jobs.

rubr_flow:convert

Convert and validate rubr_flow procedure blocks.

Errors

Failures use stable, safe codes.

Every error response carries a machine-readable code, a human message, and a request identifier where available, so clients can branch on the code, not the prose.

Error codes
ai_circuit_breaker_open
credit_limit_exceeded
forbidden
rate_limit_exceeded
unauthorized
usage_limit_exceeded
validation_failed
Error response
{
  "error": {
    "code": "unauthorized",
    "message": "The request is valid.",
    "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
    "details": [
      {}
    ]
  }
}
OpenAPI reference

48 operations, generated from the contract.

Each request and response example is generated from the operation's OpenAPI schema, so the reference can never drift from the live contract. Expand any endpoint for its curl request and JSON response.

Artifact Bundles

One artifact under review plus its references, examples, tests, generated files, and full version history.

6 operations
GET

List 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`.

artifact_bundles:read
artifacts:pull
200
400
401
403
429
Parameters
query: status
query: limit
query: offset
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "skill",
          "status": "active",
          "isPrimary": true,
          "sizeBytes": 1,
          "contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
          "latestVersionNumber": 1,
          "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": "upload",
          "contentHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
          "sizeBytes": 1,
          "parentVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
        }
      }
    ],
    "pagination": {
      "limit": 1,
      "offset": 0,
      "nextOffset": 1,
      "nextCursor": null
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
POST

Create 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`.

artifact_bundles:write
201
400
401
403
429
Request
curl -X POST "https://www.rubrkit.com/api/v1/artifact-bundles" \
  -H "Authorization: Bearer <rubrkit_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "Onboarding instruction bundle",
  "description": "System prompt and skills for the onboarding assistant.",
  "settings": {
    "defaultRubricKey": "clarity"
  }
}'
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": "text/markdown",
          "detectedLanguage": "markdown",
          "storageProvider": "vercel_blob"
        }
      },
      "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

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`.

artifact_bundles:read
artifacts:pull
200
400
401
403
404
Parameters
path: artifactBundleId *
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "text/markdown",
          "detectedLanguage": "markdown",
          "storageProvider": "vercel_blob"
        }
      },
      "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": "markdown",
      "isPrimary": true,
      "sizeBytes": 0
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
PATCH

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.

artifact_bundles:write
200
400
401
403
404
409
Parameters
path: artifactBundleId *
Request
curl -X PATCH "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
  -H "Authorization: Bearer <rubrkit_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
  "description": "Refined onboarding assistant instructions."
}'
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": "text/markdown",
          "detectedLanguage": "markdown",
          "storageProvider": "vercel_blob"
        }
      },
      "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": "markdown",
      "isPrimary": true,
      "sizeBytes": 0
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
DELETE

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`.

artifact_bundles:write
200
400
401
403
404
Parameters
path: artifactBundleId *
Request
curl -X DELETE "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "text/markdown",
          "detectedLanguage": "markdown",
          "storageProvider": "vercel_blob"
        }
      },
      "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"
}
DELETE

Permanently delete an artifact bundle.

Permanently deletes an archived artifact bundle and cascades to all of its files, file versions, and run history. This is irreversible and only succeeds when the bundle is already archived; archive it first with `DELETE /artifact-bundles/{artifactBundleId}`. API-key callers must include `artifact_bundles:write`.

artifact_bundles:write
200
400
401
403
404
409
Parameters
path: artifactBundleId *
Request
curl -X DELETE "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/permanent" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 200
{
  "data": {
    "artifactBundle": {
      "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "deleted": true
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}

Files

Upload, read, edit, and inspect the individual files inside an artifact bundle.

5 operations
GET

List 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`.

files:read
artifacts:pull
200
400
401
403
404
429
Parameters
path: artifactBundleId *
query: limit
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/files" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "markdown",
      "isPrimary": true,
      "sizeBytes": 0
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
POST

Upload 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`.

files:write
201
400
401
403
404
409
429
503
Parameters
path: artifactBundleId *
Request
curl -X POST "https://www.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",
      "mediaType": "text/markdown",
      "message": "Add the initial onboarding prompt."
    }
  ]
}'
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": "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"
}
GET

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`.

files:read
artifacts:pull
200
400
401
403
404
Parameters
path: artifactBundleId *
path: fileId *
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/files/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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

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`.

files:write
200
400
401
403
404
429
503
Parameters
path: artifactBundleId *
path: fileId *
Request
curl -X PUT "https://www.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",
  "mediaType": "text/markdown",
  "message": "Clarify the first onboarding step."
}'
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

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`.

files:write
200
400
401
403
404
409
429
Parameters
path: artifactBundleId *
path: fileId *
Request
curl -X DELETE "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/files/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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

Walk the version history of a bundle or a single file and restore an earlier revision.

5 operations
GET

List 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`.

artifact_bundles:read
artifacts:pull
200
400
401
403
404
Parameters
path: artifactBundleId *
query: limit
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/versions" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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

Restore 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`.

artifact_bundles:write
files:write
200
400
401
403
404
409
429
503
Parameters
path: artifactBundleId *
Request
curl -X POST "https://www.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": 3,
  "message": "Roll back to the reviewed onboarding copy."
}'
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": "text/markdown",
          "detectedLanguage": "markdown",
          "storageProvider": "vercel_blob"
        }
      },
      "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": "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"
          }
        }
      }
    ],
    "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

List file versions.

Lists immutable file versions in newest-first order. API-key callers must include `files:read` or `artifacts:pull`.

files:read
artifacts:pull
200
400
401
403
404
Parameters
path: artifactBundleId *
path: fileId *
query: limit
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/files/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/versions" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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

Read a specific file version.

Returns immutable file-version metadata and text content. API-key callers must include `files:read` or `artifacts:pull`.

files:read
artifacts:pull
200
400
401
403
404
Parameters
path: artifactBundleId *
path: fileId *
path: versionNumber *
Request
curl -X GET "https://www.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>"
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

Restore 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`.

files:write
200
400
401
403
404
429
503
Parameters
path: artifactBundleId *
path: fileId *
path: versionNumber *
Request
curl -X POST "https://www.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 '{
  "message": "Restore the reviewed onboarding version."
}'
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

Run rubric scoring, critique, and improvement passes over an instruction artifact.

5 operations
GET

List 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`.

artifact_bundles:read
200
400
401
403
404
Parameters
path: artifactBundleId *
query: limit
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/audits" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "clarity",
        "rubricVersion": "1.0.0",
        "artifactType": "prompt",
        "summary": {}
      }
    ],
    "pagination": {
      "limit": 1,
      "offset": 0,
      "nextOffset": 1,
      "nextCursor": null
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
POST

Start 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`.

audits:run
202
400
401
402
403
404
409
429
503
Parameters
path: artifactBundleId *
Request
curl -X POST "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/audits" \
  -H "Authorization: Bearer <rubrkit_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
  "targetFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
  "targetVersionNumber": 2,
  "artifactType": "skill",
  "rubricKey": "clarity",
  "force": false
}'
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": "clarity",
      "rubricVersion": "1.0.0",
      "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": "artifact_bundle",
      "resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "attempts": 0
    },
    "jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
    "creditCost": {
      "credits": 0,
      "reason": "requested_by_user",
      "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

Estimate 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`.

audits:run
200
400
401
403
404
409
429
Parameters
path: artifactBundleId *
Request
curl -X POST "https://www.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 '{
  "targetFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
  "targetVersionNumber": 2,
  "artifactType": "skill",
  "rubricKey": "clarity",
  "force": false
}'
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": "requested_by_user",
      "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

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`.

artifact_bundles:read
200
400
401
403
404
Parameters
path: artifactBundleId *
path: auditRunId *
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/audits/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "clarity",
      "rubricVersion": "1.0.0",
      "artifactType": "prompt",
      "summary": {}
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
POST

Apply an audit's AI rewrite to the bundle files.

Writes a new version of every file the audit rewrote. A whole-bundle audit applies each file in its improvedFiles set; a single-file-target audit applies its improvedVersion to that one file. Frontmatter is preserved per file. API-key callers must include `audits:run`.

audits:run
200
400
401
403
404
409
Parameters
path: artifactBundleId *
path: auditRunId *
Request
curl -X POST "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/audits/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/apply" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 200
{
  "data": {
    "appliedCount": 1,
    "files": [
      {
        "fileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
        "path": "prompts/main.md",
        "versionNumber": 1
      }
    ]
  }
}

rubr_flow

Convert, validate, and certify rubr_flow procedure blocks programmatically.

3 operations
GET

List 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`.

artifact_bundles:read
200
400
401
403
404
429
Parameters
path: artifactBundleId *
query: limit
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/rubr-flow/conversions" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "1.0.0",
        "sourceSummary": {},
        "sourceMapping": {}
      }
    ],
    "pagination": {
      "limit": 1,
      "offset": 0,
      "nextOffset": 1,
      "nextCursor": null
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
POST

Start 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`.

rubr_flow:convert
202
400
401
402
403
404
409
429
503
Parameters
path: artifactBundleId *
Request
curl -X POST "https://www.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 '{
  "targetFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
  "outputPath": "generated/rubr_flow.rubr_flow"
}'
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": "1.0.0",
      "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": "artifact_bundle",
      "resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "attempts": 0
    },
    "jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
    "creditCost": {
      "credits": 0,
      "reason": "requested_by_user",
      "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

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`.

artifact_bundles:read
200
400
401
403
404
Parameters
path: artifactBundleId *
path: conversionId *
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/rubr-flow/conversions/1" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "1.0.0",
      "sourceSummary": {},
      "sourceMapping": {}
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}

Evals

Define test cases, run regressions, and pull the proof report that backs a rewrite.

5 operations
GET

List 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`.

artifact_bundles:read
200
400
401
403
404
429
Parameters
path: artifactBundleId *
query: limit
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/evals" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "1.0.0",
        "scenarioCount": 0,
        "passCount": 0,
        "failCount": 0,
        "cases": [
          {
            "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
            "name": "Onboarding instruction bundle",
            "type": "standard",
            "input": "Summarize the onboarding guide in two sentences.",
            "expectedBehavior": "The response names the single next action to take.",
            "passCriteria": "Passes when the next action is explicit and unambiguous."
          }
        ]
      }
    ],
    "pagination": {
      "limit": 1,
      "offset": 0,
      "nextOffset": 1,
      "nextCursor": null
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
POST

Start 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`.

evals:run
202
400
401
402
403
404
409
429
503
Parameters
path: artifactBundleId *
Request
curl -X POST "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/evals" \
  -H "Authorization: Bearer <rubrkit_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
  "sourceFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
  "candidateFileId": "018f3e9d-7a72-73f4-9b7f-7f0a97f7abcd",
  "rubricVersion": "1.0.0",
  "maxCases": 6,
  "mode": "standard",
  "testCases": [
    {
      "id": "case-1",
      "name": "Names the next action",
      "type": "scenario",
      "input": "Summarize the onboarding guide in two sentences.",
      "expectedBehavior": "The response names the single next action to take.",
      "passCriteria": "Passes when the next action is explicit and unambiguous."
    }
  ]
}'
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": "1.0.0",
      "scenarioCount": 0,
      "passCount": 0,
      "failCount": 0,
      "cases": [
        {
          "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
          "name": "Onboarding instruction bundle",
          "type": "scenario",
          "input": "Summarize the onboarding guide in two sentences.",
          "expectedBehavior": "The response names the single next action to take.",
          "passCriteria": "Passes when the next action is explicit and unambiguous."
        }
      ]
    },
    "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": "artifact_bundle",
      "resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "attempts": 0
    },
    "jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
    "creditCost": {
      "credits": 0,
      "reason": "requested_by_user",
      "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

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`.

artifact_bundles:read
200
400
401
403
404
Parameters
path: artifactBundleId *
path: evalRunId *
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/evals/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "1.0.0",
      "scenarioCount": 0,
      "passCount": 0,
      "failCount": 0,
      "cases": [
        {
          "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
          "name": "Onboarding instruction bundle",
          "type": "scenario",
          "input": "Summarize the onboarding guide in two sentences.",
          "expectedBehavior": "The response names the single next action to take.",
          "passCriteria": "Passes when the next action is explicit and unambiguous."
        }
      ]
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
POST

Start 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`.

evals:run
202
400
401
402
403
404
409
429
503
Parameters
path: artifactBundleId *
Request
curl -X POST "https://www.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 '{
  "evalRunId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
  "includeExport": true
}'
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": "1.0.0",
      "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": "artifact_bundle",
      "resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "attempts": 0
    },
    "jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
    "creditCost": {
      "credits": 0,
      "reason": "requested_by_user",
      "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

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`.

artifact_bundles:read
200
400
401
403
404
Parameters
path: artifactBundleId *
path: proofReportId *
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/proof-reports/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "1.0.0",
      "artifactHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}

Golden Cases

Pin the cases an artifact must keep passing, and retire the ones that no longer apply without losing the record.

4 operations
GET

List golden cases for an artifact bundle.

Lists the curated golden cases pinned to an artifact bundle owned by the authenticated user. Pass `status=active` or `status=retired` to narrow the set; any other value lists everything. API-key callers must include `artifact_bundles:read`.

artifact_bundles:read
200
400
401
403
404
429
Parameters
path: artifactBundleId *
query: status
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/golden-cases" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 200
{
  "data": {
    "goldenCases": [
      {
        "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
        "artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
        "input": {},
        "expectedOutput": {},
        "criteria": {},
        "origin": "audit",
        "originRef": {},
        "weight": 1,
        "status": "active",
        "tags": [
          "edge-case"
        ]
      }
    ]
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
POST

Add a golden case.

Pins a new golden case to an artifact bundle. `input` is required and must be a non-empty JSON object; the remaining fields default to empty objects, `origin: human`, `weight: 1`, and an empty tag list. API-key callers must include `artifact_bundles:write`.

artifact_bundles:write
201
400
401
403
404
429
Parameters
path: artifactBundleId *
Request
curl -X POST "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/golden-cases" \
  -H "Authorization: Bearer <rubrkit_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
  "input": {
    "prompt": "Summarize the onboarding guide in two sentences."
  },
  "expectedOutput": {
    "summary": "A concise two-sentence summary that names the next action."
  },
  "criteria": {
    "mustNameNextAction": true
  },
  "origin": "audit",
  "originRef": {
    "auditRunId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
  },
  "weight": 2,
  "tags": [
    "edge-case",
    "onboarding"
  ]
}'
Response · 201
{
  "data": {
    "goldenCase": {
      "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "input": {},
      "expectedOutput": {},
      "criteria": {},
      "origin": "audit",
      "originRef": {},
      "weight": 1,
      "status": "active",
      "tags": [
        "edge-case"
      ]
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
GET

Get a golden case.

Returns one golden case owned by the authenticated user. API-key callers must include `artifact_bundles:read`.

artifact_bundles:read
200
400
401
403
404
Parameters
path: goldenCaseId *
Request
curl -X GET "https://www.rubrkit.com/api/v1/golden-cases/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 200
{
  "data": {
    "goldenCase": {
      "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "input": {},
      "expectedOutput": {},
      "criteria": {},
      "origin": "audit",
      "originRef": {},
      "weight": 1,
      "status": "active",
      "tags": [
        "edge-case"
      ]
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
DELETE

Retire a golden case.

Retires a golden case instead of deleting it. The record is preserved as evidence with `status: retired` and is returned in the response, so the history of what was once required to pass stays intact. API-key callers must include `artifact_bundles:write`.

artifact_bundles:write
200
400
401
403
404
Parameters
path: goldenCaseId *
Request
curl -X DELETE "https://www.rubrkit.com/api/v1/golden-cases/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 200
{
  "data": {
    "goldenCase": {
      "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "input": {},
      "expectedOutput": {},
      "criteria": {},
      "origin": "audit",
      "originRef": {},
      "weight": 1,
      "status": "active",
      "tags": [
        "edge-case"
      ]
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}

Drift

Watch a pinned version on a schedule and get told when its scores move beyond its own measured noise floor.

6 operations
GET

List drift monitors for an artifact bundle.

Lists the drift monitors the authenticated user has created for an artifact bundle. API-key callers must include `artifact_bundles:read`.

artifact_bundles:read
200
400
401
403
429
Parameters
path: artifactBundleId *
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/drift-monitors" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 200
{
  "data": {
    "driftMonitors": [
      {
        "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
        "artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
        "pinnedVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
        "cadence": "daily",
        "repeats": 2,
        "status": "active",
        "baseline": {
          "mean0": 1,
          "sd0": 1,
          "n": 1
        },
        "lastCheckedAt": "2026-06-15T12:00:00.000Z",
        "nextCheckAt": "2026-06-15T12:00:00.000Z",
        "createdAt": "2026-06-15T12:00:00.000Z"
      }
    ]
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
POST

Create a drift monitor.

Starts watching one immutable file version inside the artifact bundle for score drift. `pinnedVersionId` is required and must belong to this artifact bundle. The monitor is created due immediately: its first run calibrates the noise floor rather than judging against it. Every active monitor spends credits on a schedule, so accounts are capped on how many may be active at once. API-key callers must include `artifact_bundles:write`.

artifact_bundles:write
201
400
401
403
404
429
Parameters
path: artifactBundleId *
Request
curl -X POST "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/drift-monitors" \
  -H "Authorization: Bearer <rubrkit_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
  "pinnedVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
  "cadence": "weekly",
  "repeats": 3,
  "rubricVersion": "1.0.0"
}'
Response · 201
{
  "data": {
    "driftMonitor": {
      "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "pinnedVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "cadence": "daily",
      "repeats": 2,
      "status": "active",
      "baseline": {
        "mean0": 1,
        "sd0": 1,
        "n": 2
      },
      "lastCheckedAt": "2026-06-15T12:00:00.000Z",
      "nextCheckAt": "2026-06-15T12:00:00.000Z",
      "createdAt": "2026-06-15T12:00:00.000Z"
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
GET

Get a drift monitor.

Returns one drift monitor owned by the authenticated user, including its calibrated baseline and schedule. API-key callers must include `artifact_bundles:read`.

artifact_bundles:read
200
400
401
403
404
Parameters
path: driftMonitorId *
Request
curl -X GET "https://www.rubrkit.com/api/v1/drift-monitors/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 200
{
  "data": {
    "driftMonitor": {
      "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "pinnedVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "cadence": "daily",
      "repeats": 2,
      "status": "active",
      "baseline": {
        "mean0": 1,
        "sd0": 1,
        "n": 2
      },
      "lastCheckedAt": "2026-06-15T12:00:00.000Z",
      "nextCheckAt": "2026-06-15T12:00:00.000Z",
      "createdAt": "2026-06-15T12:00:00.000Z"
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
PATCH

Pause or resume a drift monitor.

Sets a drift monitor's status. Only `status` is read from the request body, and only `active` or `paused` are accepted. A paused monitor keeps its calibrated baseline and observation history but stops being picked up by the schedule. API-key callers must include `artifact_bundles:write`.

artifact_bundles:write
200
400
401
403
404
Parameters
path: driftMonitorId *
Request
curl -X PATCH "https://www.rubrkit.com/api/v1/drift-monitors/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
  -H "Authorization: Bearer <rubrkit_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
  "status": "paused"
}'
Response · 200
{
  "data": {
    "driftMonitor": {
      "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "pinnedVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "cadence": "daily",
      "repeats": 2,
      "status": "active",
      "baseline": {
        "mean0": 1,
        "sd0": 1,
        "n": 2
      },
      "lastCheckedAt": "2026-06-15T12:00:00.000Z",
      "nextCheckAt": "2026-06-15T12:00:00.000Z",
      "createdAt": "2026-06-15T12:00:00.000Z"
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
POST

Run a drift check now.

Queues a drift check immediately instead of waiting for the monitor's cadence, and returns the async `drift_check` job to poll at `/jobs/{jobId}`. The run goes through the same metered and refunded job path as the scheduled sweep. Manual runs are deliberately not deduplicated against the due window, so asking for a second check on purpose queues a second job. API-key callers must include `artifact_bundles:write`.

artifact_bundles:write
201
400
401
402
403
404
429
503
Parameters
path: driftMonitorId *
Request
curl -X POST "https://www.rubrkit.com/api/v1/drift-monitors/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/check" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 201
{
  "data": {
    "driftMonitor": {
      "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "pinnedVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "cadence": "daily",
      "repeats": 2,
      "status": "active",
      "baseline": {
        "mean0": 1,
        "sd0": 1,
        "n": 2
      },
      "lastCheckedAt": "2026-06-15T12:00:00.000Z",
      "nextCheckAt": "2026-06-15T12:00:00.000Z",
      "createdAt": "2026-06-15T12:00:00.000Z"
    },
    "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": "artifact_bundle",
      "resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "attempts": 0
    },
    "jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
GET

List drift observations.

Returns the recorded observations for a drift monitor. Calibration runs establish the baseline and do not produce an observation, so a monitor that has only ever calibrated returns an empty list. API-key callers must include `artifact_bundles:read`.

artifact_bundles:read
200
400
401
403
404
Parameters
path: driftMonitorId *
Request
curl -X GET "https://www.rubrkit.com/api/v1/drift-monitors/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/observations" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 200
{
  "data": {
    "observations": [
      {
        "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
        "observedAt": "2026-06-15T12:00:00.000Z",
        "sampleCount": 0,
        "drifted": true,
        "direction": "up",
        "reason": "ewma_out_of_band",
        "metrics": {
          "drifted": true,
          "direction": "up",
          "lastEwma": 1,
          "band": [
            1
          ],
          "exceededBy": 1,
          "cusumBreach": true,
          "reason": "ewma_out_of_band"
        }
      }
    ]
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}

Outcomes

Feed production results back in to see whether your inputs have shifted and whether the rubric still predicts reality.

4 operations
GET

List recorded outcomes for an artifact bundle.

Lists the production outcome events recorded against an artifact bundle owned by the authenticated user. API-key callers must include `artifact_bundles:read`.

artifact_bundles:read
200
400
401
403
404
429
Parameters
path: artifactBundleId *
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/outcomes" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 200
{
  "data": {
    "outcomes": [
      {
        "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
        "artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
        "artifactVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
        "inputHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
        "inputFeature": 1,
        "outcomeMetric": 1,
        "outcomeLabel": "Product updates",
        "occurredAt": "2026-06-15T12:00:00.000Z",
        "createdAt": "2026-06-15T12:00:00.000Z"
      }
    ]
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
POST

Record a production outcome.

Records one production outcome event against an artifact bundle. At least one of `outcomeMetric`, `outcomeLabel`, or `inputFeature` must be present; a body carrying none of them is rejected. `inputFeature` feeds the input drift reading and `outcomeMetric` feeds the rubric-validity reading, so supplying both over time is what makes those endpoints usable. API-key callers must include `artifact_bundles:write`.

artifact_bundles:write
201
400
401
403
404
429
Parameters
path: artifactBundleId *
Request
curl -X POST "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/outcomes" \
  -H "Authorization: Bearer <rubrkit_api_key>" \
  -H "Content-Type: application/json" \
  --data '{
  "artifactVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
  "inputHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
  "inputFeature": 0.82,
  "outcomeMetric": 0.91,
  "outcomeLabel": "resolved",
  "occurredAt": "2026-06-15T12:00:00.000Z"
}'
Response · 201
{
  "data": {
    "outcome": {
      "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "artifactBundleId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "artifactVersionId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "inputHash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
      "inputFeature": 1,
      "outcomeMetric": 1,
      "outcomeLabel": "Product updates",
      "occurredAt": "2026-06-15T12:00:00.000Z",
      "createdAt": "2026-06-15T12:00:00.000Z"
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
GET

Read input drift.

Compares the `inputFeature` values of recently recorded outcomes against the immediately preceding window of the same length and returns a population stability index (PSI) reading. The recent window is the last `windowDays` days; the reference window is the `windowDays` before that. When either side has fewer than `binCount * 5` usable values the reading is returned with `reliable: false` and `interpretation: insufficient_data`. API-key callers must include `artifact_bundles:read`.

artifact_bundles:read
200
400
401
403
404
Parameters
path: artifactBundleId *
query: windowDays
query: binCount
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/drift/input" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 200
{
  "data": {
    "inputDrift": {
      "psi": 1,
      "interpretation": "stable",
      "reliable": true,
      "reason": "requested_by_user",
      "binCount": 1,
      "referenceCount": 0,
      "actualCount": 0,
      "windowDays": 1,
      "referenceWindow": [
        "2026-06-15T12:00:00.000Z"
      ],
      "recentWindow": [
        "2026-06-15T12:00:00.000Z"
      ]
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
GET

Read rubric-validity drift.

Correlates the latest audit score for each artifact version against the `outcomeMetric` of the outcomes recorded for that version, answering whether the rubric still predicts real-world results. Only outcomes that carry both an `artifactVersionId` and a finite `outcomeMetric`, and whose version has a usable audit score, form a pair. Fewer than 10 pairs returns `reliable: false` with `interpretation: insufficient_data` and no correlation. API-key callers must include `artifact_bundles:read`.

artifact_bundles:read
200
400
401
403
404
Parameters
path: artifactBundleId *
Request
curl -X GET "https://www.rubrkit.com/api/v1/artifact-bundles/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/drift/validity" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 200
{
  "data": {
    "validityDrift": {
      "reliable": true,
      "interpretation": "predictive",
      "pairCount": 0,
      "correlation": 1
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}

Credits

Read the credit balance and ledger, and preview what an operation will cost before you run it.

1 operation
GET

Get 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.

credits:read
200
400
401
403
429
Parameters
query: limit
Request
curl -X GET "https://www.rubrkit.com/api/v1/credits" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "artifact_bundle",
        "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

Poll status and progress events for the long-running, asynchronous work other resources kick off.

3 operations
GET

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`.

jobs:read
200
400
401
403
404
429
Parameters
path: jobId *
Request
curl -X GET "https://www.rubrkit.com/api/v1/jobs/018f3e9d-7a72-73f4-9b7f-7f0a97f71234" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "artifact_bundle",
      "resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "attempts": 0
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
GET

List 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`.

jobs:read
200
400
401
403
404
429
Parameters
path: jobId *
query: limit
Request
curl -X GET "https://www.rubrkit.com/api/v1/jobs/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/events" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 200
{
  "data": {
    "events": [
      {
        "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
        "jobId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
        "state": "queued",
        "phase": "preparing_context",
        "percent": 0,
        "message": "The request is valid.",
        "event": {},
        "createdAt": "2026-06-15T12:00:00.000Z"
      }
    ],
    "pagination": {
      "limit": 1,
      "offset": 0,
      "nextOffset": 1,
      "nextCursor": null
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}
POST

Cancel 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`.

jobs:write
200
400
401
403
404
409
429
Parameters
path: jobId *
Request
curl -X POST "https://www.rubrkit.com/api/v1/jobs/018f3e9d-7a72-73f4-9b7f-7f0a97f71234/cancel" \
  -H "Authorization: Bearer <rubrkit_api_key>"
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": "artifact_bundle",
      "resourceId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "attempts": 0
    }
  },
  "requestId": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234"
}

Auth

Session identity and authenticated-user metadata for first-party clients.

1 operation
GET

Get 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.

200
401
403
409
503
Request
curl -X GET "https://www.rubrkit.com/api/v1/me" \
  -H "Authorization: Bearer <rubrkit_api_key>"
Response · 200
{
  "data": {
    "user": {
      "id": "018f3e9d-7a72-73f4-9b7f-7f0a97f71234",
      "email": "api-user@rubrkit.dev",
      "status": "active",
      "planKey": "free",
      "displayName": "Onboarding instruction bundle",
      "avatarUrl": "https://www.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": "Google",
        "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"
}

Make your first authenticated call.

Create a scoped key, send it as a bearer token, and call the operations above. Or grade an instruction first to see what the audit and eval endpoints return.

Create API keysRun an audit