API reference · v1
Check versions against a range
Check up to 100 versions against an npm, Cargo, PEP 440 (pip) or Go module range in one call; return each result, the versions sorted by precedence, and the highest and lowest satisfying versions. Pre-releases follow npm/Cargo rules: 1.3.0-beta.1 satisfies only a range that names a pre-release of 1.3.0. Go compares the minimum required version within the same major version. Requires a credential with tools.run; every accepted call consumes one monthly unit, including business 4xx/5xx.
/v1/run/semver/checkAccess requirements
Health, metadata, changelog and waitlist routes are public. Catalog reads (GET /v1/tools, /v1/tools/{id}, /v1/colors/*) and POST /v1/tools/query require a tools.read credential; POST /v1/run/* requires tools.run. There is no anonymous access to these routes: send an API key (Bearer OR X-API-Key) from your server, or use the HttpOnly main-site session plus workspace selection and same-origin Origin. Never combine credentials. Every admitted call is metered. Ingress and workspace/actor minute/month limits are separate; waitlist has its own policy.
Implemented interfaces and development screens do not imply public production availability, paid access or a completed payment integration. Confirm access with Birdor before connecting an application. No paid Pro service, activation or cross-device sync is currently delivered. We are validating one repeatable task before building a paid offer.
Parameters
| Field | Description |
|---|---|
AuthorizationstringOptional | Bearer API key with tools.run; alternatively X-API-Key. One of the credentials is required. |
X-API-KeystringOptional | Alternative to Authorization; never send both. |
X-Birdor-Workspace-IDstringOptional | Required with the site session; optional and matching with an API key. |
X-Birdor-Project-IDstringOptional | Optional owned project; a project-bound key cannot select another project. |
Request body
Send JSON with Content-Type: application/json.
| Field | Description |
|---|---|
ecosystemnpm | cargo | pip | goOptional | Range semantics: npm (node-semver), cargo (Cargo.toml requirements), pip (PEP 440 specifiers) or go (minimum version, same major); default npm. |
rangestringRequired | Range or requirement, e.g. ^1.2.0 || ~0.4.1 (npm), >=1.2, <1.5 (cargo), >=1.4,!=1.4.2 (pip) or v1.2.0 (go); at most 256 characters. |
versionsarrayRequired | Versions to check, 1–100 entries of at most 64 characters. Invalid entries are reported per item instead of failing the request. |
Request example
curl --request POST "$BIRDOR_API_BASE_URL/v1/run/semver/check" \
--header "Accept: application/json" \
--header "Authorization: Bearer $BIRDOR_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"ecosystem": "npm",
"range": "^1.2.0",
"versions": [
"1.1.9",
"1.2.0",
"1.10.3",
"1.11.0-rc.1",
"2.0.0",
"latest"
]
}'Examples are copied only; this page does not send API requests.
Responses
Illustrative response. Values vary by environment and time.
200Success
{
"ok": true,
"data": {
"ecosystem": "npm",
"range": "^1.2.0",
"normalizedRange": ">=1.2.0 <2.0.0",
"results": [
{
"version": "1.1.9",
"valid": true,
"satisfied": false,
"reason": null
},
{
"version": "1.2.0",
"valid": true,
"satisfied": true,
"reason": null
},
{
"version": "1.10.3",
"valid": true,
"satisfied": true,
"reason": null
},
{
"version": "1.11.0-rc.1",
"valid": true,
"satisfied": false,
"reason": null
},
{
"version": "2.0.0",
"valid": true,
"satisfied": false,
"reason": null
},
{
"version": "latest",
"valid": false,
"satisfied": false,
"reason": "\"latest\" is not a valid MAJOR.MINOR.PATCH version"
}
],
"sorted": [
"1.1.9",
"1.2.0",
"1.10.3",
"1.11.0-rc.1",
"2.0.0"
],
"satisfiedCount": 2,
"maxSatisfying": "1.10.3",
"minSatisfying": "1.2.0"
},
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}400Invalid JSON, schema validation failure (field paths/codes only, never input values) or ambiguous credentials
{
"ok": false,
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}401Missing, expired, rotated, revoked or invalid credential; there is no anonymous access
{
"ok": false,
"code": "UNAUTHENTICATED",
"message": "API access denied",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}403Key lacks tools.run, or workspace/project/member policy or site Origin denied
{
"ok": false,
"code": "FORBIDDEN",
"message": "API access denied",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}405Only POST is supported; rejected before admission
{
"ok": false,
"code": "METHOD_NOT_ALLOWED",
"message": "Method not allowed",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}408Body read exceeds five seconds; before admission
{
"ok": false,
"code": "REQUEST_TIMEOUT",
"message": "Request body timeout or aborted",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}413Body exceeds 8192 bytes; before admission
{
"ok": false,
"code": "PAYLOAD_TOO_LARGE",
"message": "Request body too large",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}415Content-Type must be application/json; before admission
{
"ok": false,
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "JSON content type required",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}429Ingress, workspace/actor minute or monthly quota exceeded; inspect code and Retry-After
{
"ok": false,
"code": "QUOTA_EXCEEDED",
"message": "API request limit exceeded",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}500Unexpected operation failure; details are never echoed
{
"ok": false,
"code": "OPERATION_FAILED",
"message": "Operation failed",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}503Authentication/metering dependency unavailable
{
"ok": false,
"code": "API_GATEWAY_UNAVAILABLE",
"message": "API access denied",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}422INVALID_RANGE: range cannot be parsed for the ecosystem; details.reason explains why
{
"ok": false,
"code": "INVALID_RANGE",
"message": "range cannot be parsed for the ecosystem; details.reason explains why",
"request_id": "req_example",
"timestamp": "2026-10-11T00:00:00.000Z"
}Example response fields
Fields shown in this example; optional fields can be omitted. Array rows describe the first example element.
- okboolean
- Application success flag.
- dataobject
- Endpoint-specific result.
- data.ecosystemstring
- Endpoint-specific example value.
- data.rangestring
- Endpoint-specific example value.
- data.normalizedRangestring
- Endpoint-specific example value.
- data.resultsarray
- Endpoint-specific example value.
- data.results[].versionstring
- Version string.
- data.results[].validboolean
- True when the signature matches and any signed timestamp is within tolerance.
- data.results[].satisfiedboolean
- Endpoint-specific example value.
- data.results[].reasonnull
- Endpoint-specific example value.
- data.sortedarray
- Endpoint-specific example value.
- data.satisfiedCountnumber
- Endpoint-specific example value.
- data.maxSatisfyingstring
- Endpoint-specific example value.
- data.minSatisfyingstring
- Endpoint-specific example value.
- request_idstring
- Origin-response identifier matching X-Request-ID; a shared HTTP cache may replay the original trace.
- timestampstring
- Response creation timestamp.