Run Covecta workflows from your own systems

Overview

What the API does, and what it deliberately does not.

Covecta analyses documents you have already ingested and returns structured findings — a valuation review, a credit summary, a completed assessment. The API is the machine entry point to that: you start a workflow run against documents and an account, and read back its status and outcome.

Requests are reference-shaped. You send identifiers and parameters — a document id, an account id, workflow input — never document bodies and never raw personal data. Covecta already holds the documents, and a run’s input is stored in plaintext by the workflow engine, so keeping submissions to references is a requirement, not a preference.

Every call is scoped to your tenant by the token you present. There is no parameter that widens that scope.

Your base URL

Covecta runs regionally, and your base URL is the one we give you when we register your client — every path in this documentation is relative to it. In production that is https://api.prod.covecta.io (EU) or https://api.produs.covecta.io (US). Staging and development environments have their own hosts.

The base URL is also the token aud and the OAuth issuer, so it is worth reading from configuration rather than hard-coding it in more than one place.

How integration works

Four steps, once each. Steps 1 and 2 you do once per environment; steps 3 and 4 are the loop your integration runs.

The asynchronous model

A run moves from RUNNING to exactly one terminal status. Stop polling when you reach one:

INTERRUPTED means the run paused for a human decision; ESCALATED means it was referred to a person. Both are final as far as your integration is concerned — no further polling will change them.

Authentication

One token, accepted by every surface below.

Covecta uses the OAuth 2.0 client_credentials grant with a signed private_key_jwt client assertion (RFC 7523). You hold the private key and we hold only its public half, so there is no shared secret that can leak from either side — and nothing to rotate in a hurry if one of your other vendors is breached.

The token you receive is a short-lived JWT bound to your tenant. Send it as a bearer token on every subsequent call.

The client assertion

Build a JWT, sign it with your registered private key, and set kid in the header to the key version we issued you. These claims are required and verified:

Requesting a token

import time, jwt, requests

CLIENT_ID   = "6f3a91c4-2b7e-4a05-9d18-8c5e2f7b0a44"
KEY_VERSION = "1"                        # the kid we issued with your client
ISSUER      = "https://api.prod.covecta.io"   # your region's base URL — see Overview
PRIVATE_KEY = open("covecta-client-key.pem").read()

now = int(time.time())
assertion = jwt.encode(
    {
        "iss": CLIENT_ID,
        "sub": CLIENT_ID,
        "aud": ISSUER,
        "iat": now,
        "exp": now + 300,      # 5 minutes is the hard maximum
    },
    PRIVATE_KEY,
    algorithm="ES256",         # ES256 or PS256 — never RS256
    headers={"kid": KEY_VERSION},
)

response = requests.post(
    f"{ISSUER}/oauth/token",
    data={
        "grant_type": "client_credentials",
        "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
        "client_assertion": assertion,
        "scope": "run:invoke run:read",
    },
    timeout=10,
)
token = response.json()["access_token"]

Cache the token until shortly before expires_in elapses and reuse it. Do not mint one per request — you will be signing a JWT and paying a round trip for no benefit.

Endpoints

Read the discovery document at startup rather than hard-coding endpoints — it names the token endpoint, the grants and client-authentication methods we accept, the signing algorithms allowed on assertions, and the scopes a client may hold.

Use the JWK Set if you want to validate our access tokens yourself. Keys rotate: resolve a token’s kid against this document, and refetch when you meet a kid you do not recognise.

Discovery

Every run submission references ids — which workflow to run, which account it belongs to, which documents to process. These read-only endpoints resolve those ids, so you never have to leave the API to find what to submit. All three require the run:read scope and return only your own tenant’s data.

List workflows

The workflows your tenant can invoke. Submit a run with the studio_workflow_id you get here.

List accounts

The accounts in your tenant. Submit a run with the account_id you get here.

List an account’s documents

An account’s source documents. Each carries ingested: a run against a document that has not finished ingesting has no content to read yet, so wait for ingested: true before submitting it.

Workflow runs over REST

Submit a run, then poll it. Three endpoints in total.

Submit a run

{
  "account_id": "0190f3c1-8a4e-7c2b-9f10-1a2b3c4d5e6f",
  "documents": [
    {
      "doc_type": "valuation",
      "document_id": "0190f3c1-8a4e-7c2b-9f10-3d5e7a9b1c2d"
    }
  ],
  "input": {
    "vecta_workflow_slug": "valuation-review"
  },
  "workflow_id": "autonomous-valuation-analysis"
}

{
  "status": "ACCEPTED",
  "workflow_run_id": "0190f3c1-8a4e-7c2b-9f10-7b8c9d0e1f2a"
}

The workflow_run_id is minted at submission, so you can record it against your own case immediately. It becomes readable a moment later, once the run starts.

Poll a run

This is the endpoint your integration polls. Read it until status is terminal.

{
  "account_id": "0190f3c1-8a4e-7c2b-9f10-1a2b3c4d5e6f",
  "decision": "APPROVED",
  "document_ids": [
    "0190f3c1-8a4e-7c2b-9f10-3d5e7a9b1c2d"
  ],
  "finished_at": "2026-07-29T09:17:48.006Z",
  "generated_document_id": "0190f3d5-1c22-7a41-8e03-9f7b2c6d4e11",
  "started_at": "2026-07-29T09:14:02.481Z",
  "status": "COMPLETED",
  "workflow_id": "autonomous-valuation-analysis",
  "workflow_name": "Valuation review",
  "workflow_run_id": "0190f3c1-8a4e-7c2b-9f10-7b8c9d0e1f2a"
}

List runs

Runs come back newest first. Paginate by passing the previous response’s next_cursor back as cursor; a null next_cursor means you have reached the last page.

Workflow runs over MCP

The same engine as Model Context Protocol tools, for agent clients.

If you are integrating an agent rather than a backend service, use the MCP endpoint instead of the REST routes. It exposes the same run core as tools, so an agent can invoke Covecta as a capability without you writing an HTTP client.

POST /mcp is a stateless streamable-HTTP MCP endpoint: one JSON-RPC message per request, one JSON response, no session id and no event stream to hold open. Tool input schemas are generated from the same models the REST surface validates, so the two cannot disagree.

Supported protocol versions: 2025-03-26 2025-06-18

Tools

Scopes are enforced per tool at call time, so a token holding only run:read can poll but cannot submit.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "invoke_workflow",
    "arguments": {
      "workflow_id": "autonomous-valuation-analysis",
      "document_id": "0190f3c1-8a4e-7c2b-9f10-3d5e7a9b1c2d",
      "account_id": "0190f3c1-8a4e-7c2b-9f10-1a2b3c4d5e6f"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "workflow_run_id": "0190f3c1-8a4e-7c2b-9f10-7b8c9d0e1f2a",
      "status": "ACCEPTED"
    },
    "isError": false
  }
}

A tool that fails returns isError: true with an explanation, rather than a JSON-RPC error — that is the MCP convention, so your agent sees the failure as a tool result it can reason about.

Discovery and auth

A 401 from /mcp carries a WWW-Authenticate header pointing at this document. A spec-following MCP client uses that to discover the whole authentication flow without being configured for it — which is the fastest path to a working integration if your client supports it.

Errors

What to retry, and what to fix.

The token endpoint returns RFC 6749 error bodies: an error code from a fixed set, plus a human-readable error_description written for whoever is debugging the integration. It never contains sensitive detail.

RFC 6749 §5.2 error response.

Retry guidance

• 400 — do not retry. The request is unusable; the message says how.
• 401 or 403 — do not retry. Fix the credentials, the assertion, or the requested scopes.
• 404 while polling — retry. The run has not become readable yet.
• 503 — retry, honouring Retry-After where present. Back off exponentially.

Scopes

Request only what you need. A polling service that never submits should hold run:read alone, so a leaked token cannot start work.

About this document

The reference on this page — every operation, field table, status list and example — is generated from the running service’s own annotations, published as an OpenAPI 3.1 contract at /v1/openapi.json and an MCP tool list at /v1/mcp-tools.json. It describes deployed behaviour rather than an intention, and it cannot drift from the API: the build fails if it tries to.