Specs

Refresh a Spec

POST
/specs/{spec_id}/refresh

Fetches the configured source now and creates a new Spec Revision only when its content changes. Diagnostics then reads that revision. If automatic generation is enabled, refresh queues generation for active Targets even when the source is unchanged. A 502 follow_up_failed means the new Spec Revision was recorded but generation could not be queued.

AuthorizationBearer <token>

Organization API key from the console (ak_...), or an OAuth access token with user:org:read, the organization selected during consent, and the capability required by the operation.

In: header

Path Parameters

spec_id*string

Unique identifier for a project's logical API Spec.

Match^spec_[a-z0-9]{16}$

Header Parameters

Idempotency-Key?string

Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write.

Match^[!-~]+$
Length1 <= length <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/specs/spec_2p8m4q7k1v9d6h3c/refresh"
{  "id": "spec_2p8m4q7k1v9d6h3c",  "object": "spec",  "project_id": "prj_4f8k2m7x9q1v6b3n",  "source": {    "type": "url",    "url": {      "url": "https://api.parcel.example/openapi.json",      "headers_configured": false    }  },  "format": "openapi",  "patches": [],  "graphql": null,  "diagnostic_policy": {    "fail_on": "error",    "only_new": false,    "suppressions": []  },  "revision_latest_id": "srev_6m1q8v4k2p9d7h3c",  "created_at": "2026-09-23T08:00:00Z",  "updated_at": "2026-09-23T08:00:00Z",  "request_id": "req_3k8m1v6q9p2d7h4c"}