Verging Memory CI API setup

Use the API directly when your repository is not on GitHub or when you are building your own integration. For GitHub Actions, start with Integrate Verging Memory CI with GitHub Actions.

export VERGING_API_BASE="https://ci.verginglabs.com"
export VERGING_API_KEY="<your API key>"

Keep the key out of your repository and logs.

Submit a release

POST /v1/releases
Authorization: Bearer $VERGING_API_KEY
Content-Type: application/json

Minimal request:

curl -X POST "$VERGING_API_BASE/v1/releases" \
  -H "Authorization: Bearer $VERGING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"vendor_version":"2.31.0","environments":["Claude Code Opus 5"]}'

vendor_version (required) : Release identifier, up to 64 characters. Use letters, digits, dots, underscores, plus signs and hyphens; do not begin with a hyphen.

product_name : Product name for the report title, up to 64 characters.

environments : An array containing one or more agent setup names exactly as shown in your onboarding details. One release produces one combined report. Duplicate names are refused.

suites : An array of suite values. Omit it to select every suite chosen during onboarding that every agent setup named on the release supports and has set up.

storage_only : true to cover the Storage step only. Defaults to false.

wiring_check : true to verify the integration without testing your product.

notes : Free text stored with the release record.

Select test suites

Omit suites to select all chosen suites: every suite chosen for your account during onboarding that every agent setup named on the release supports and has set up. A suite some named setups have and others lack is left out; the receipt's scope_summary says which setup has it and that a release naming that setup alone covers it. Every suite, Onboarding included, is supported on Claude Code and Hermes agent setups. If no suite is set up on all the named setups, the release is declined (HTTP 409, code: "not_set_up"): start one release per agent setup, or send suites.

Sending an explicit suites list is a normal way to scope releases for different sub-repositories or kinds of changes. Every named suite must be supported and set up on every named agent setup. You may send a value or its display name. Responses always use the value.

• onboarding: Onboarding
• core-recall: Core Recall
• preference-adherence: Preference Adherence
• truth-maintenance: Truth Maintenance
• history-migration: History Migration
• memory-at-scale: Memory at Scale
• long-horizon-retention: Long-Horizon Retention, available on a separately ordered tier

The Onboarding suite tests whether a fresh agent sets up your product from your published documentation, stores a memory, and recalls it in a new session.

Example with selected suites and several agent setups:

curl -X POST "$VERGING_API_BASE/v1/releases" \
  -H "Authorization: Bearer $VERGING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "vendor_version": "2.31.0",
        "environments": ["Claude Code Opus 5", "Hermes GPT-5.6 Luna"],
        "suites": ["core-recall", "truth-maintenance"]
      }'

Tests outside the selection are not tested, graded or included in scores. A narrow report is a verdict only on the selected suites.

Receipt

An accepted submission returns 202 and a receipt:

{
  "release_id": "run_20260815_186efbad9769",
  "received_at": "2026-08-15T08:25:59.868Z",
  "delivery": {
    "preliminary_report": "delivered when testing completes",
    "final_report": "grading corrections follow when needed"
  },
  "scope": {"suites": ["core-recall", "truth-maintenance"]},
  "status": "queued",
  "status_url": "/v1/releases/run_20260815_186efbad9769"
}

Store the release_id. Submission is not idempotent, so an accepted retry creates another release.

Poll status

curl -H "Authorization: Bearer $VERGING_API_KEY" \
  "$VERGING_API_BASE/v1/releases/$RELEASE_ID"

Possible status values:

• queued: accepted and waiting to start.
• held: waiting for review, payment or another stated condition. A release with a suite that is not set up is declined instead; it is never held for activation.
• running: testing is underway.
• report_ready: the preliminary report is available.
• corrected: the final report is available.
• failed: testing stopped. Follow the returned failure and fix fields.

When present, corrections_due_by is Verging Labs' internal target for finalizing the report, not a guaranteed delivery date. Passing it holds finalization and flags the release OVERDUE; it does not cancel the release.

When present, environments_unavailable lists Environments that could not be completed because their model provider was unavailable. Each entry contains agent_setup, suite, and provider; the setup uses its account name, the suite uses its request value, and the provider uses its name. Verging Labs reruns the affected work, and the Final Report includes the completed results.

Fetch the report

curl -H "Authorization: Bearer $VERGING_API_KEY" \
  "$VERGING_API_BASE/v1/releases/$RELEASE_ID/report"

The response includes:

• release_id, vendor_version, status and stage
• report_markdown, the human-readable report
• diff, the machine-readable report
• evidence, the supporting files
• corrections_due_by when a preliminary report awaits finalization

Write these values to the folder described in Integrate Verging Memory CI with GitHub Actions. Replace a preliminary report with the final report for the same release_id.

Storage-only releases

Set "storage_only": true to test the Storage step without retrieval questions. The selected suites must already be set up on exactly one named agent setup. The report is final on delivery. If you need several setups, submit one storage-only release for each setup.

Wiring checks

Set "wiring_check": true to verify the key, account configuration, report routes and your commit path. The response is immediate and uses "format": "wiring-check/v1" with "stage": "wiring". It has no verdict, so do not use it as a release gate.

The GitHub Action submits this on its own on the first push, and whenever a release is declined with HTTP 409 and code: "not_set_up".

Errors and retries

• 400: fix the named request field or value.
• 401: replace the missing, invalid or expired API key.
• 402: resolve the payment issue named in the response, then retry.
• 404: verify that the release belongs to this API key.
• 409: follow the response's fix field. A response with "code": "not_set_up" means a test suite named by the release is not set up on one of its agent setups yet; the GitHub Action performs the wiring check instead. With another CI system, contact your Verging Labs contact to set it up, or name only suites already set up on every named agent setup; use GET /v1/environments to list them. Other causes include a storage-only request whose suites are not set up on its agent setup, or a wiring check on an account with no agent setup on record.
• 429: wait for Retry-After, then retry.
• 5xx: keep the release_id if the request was accepted. Poll or fetch that release instead of submitting it again. If there was no receipt, retry with backoff.

For help, write to contact@verginglabs.com with the release_id, request without credentials, HTTP status, and response body.

See Agent setups, Read a regression report, Billing, and the Terms of Service.