Skip to API content
Birdor API v1

API reference · v1

Next cron run times

Validate a five-field cron expression (or @hourly/@daily/@weekly/@monthly/@yearly) and list its next run times in an IANA time zone. Missing wall times during DST spring-forward are skipped and repeated wall times during fall-back run twice. Runs strictly after startAt (default: now) and before startAt + windowDays. mode sets the day-of-month/day-of-week rule: generic (Vixie cron: OR when both fields are restricted), and, or. Requires a credential with tools.run; every accepted call consumes one monthly unit, including business 4xx/5xx.

POST/v1/run/cron/next

Access 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

FieldDescription
AuthorizationstringOptionalBearer API key with tools.run; alternatively X-API-Key. One of the credentials is required.
X-API-KeystringOptionalAlternative to Authorization; never send both.
X-Birdor-Workspace-IDstringOptionalRequired with the site session; optional and matching with an API key.
X-Birdor-Project-IDstringOptionalOptional owned project; a project-bound key cannot select another project.

Request body

Send JSON with Content-Type: application/json.

FieldDescription
expressionstringRequiredFive-field cron expression or @hourly/@daily/@weekly/@monthly/@yearly; at most 128 characters. Seconds fields are not supported.
timeZonestringOptionalIANA time zone such as America/New_York; default UTC.
startAtstringOptionalRFC 3339 instant with Z or an explicit offset; runs are strictly after it. Default: request time.
countintegerOptionalNumber of runs to return, 1–100; default 10.
windowDaysintegerOptionalSearch window after startAt in days, 1–365; default 365.
modegeneric | and | orOptionalDay-of-month/day-of-week rule: generic (OR when both are restricted, like Vixie cron), and, or.

Request example

1. Set the base URL

Request example
curl --request POST "$BIRDOR_API_BASE_URL/v1/run/cron/next" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $BIRDOR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "expression": "0 9 * * 1-5",
  "timeZone": "America/New_York",
  "startAt": "2026-10-09T12:00:00Z",
  "count": 2
}'

Examples are copied only; this page does not send API requests.

Responses

Illustrative response. Values vary by environment and time.

200Success
HTTP 200
{
  "ok": true,
  "data": {
    "expression": "0 9 * * 1-5",
    "timeZone": "America/New_York",
    "mode": "generic",
    "description": {
      "minute": "Custom minute pattern: 0",
      "hour": "Custom hour pattern: 9",
      "dayOfMonth": "Every day of the month",
      "month": "Every month",
      "dayOfWeek": "Custom day of week range: 1-5"
    },
    "explanation": {
      "dialect": "standard",
      "time": {
        "kind": "clock",
        "times": [
          {
            "hour": 9,
            "minute": 0
          }
        ]
      },
      "days": {
        "kind": "dow",
        "dow": {
          "kind": "range",
          "from": 1,
          "to": 5
        }
      },
      "months": {
        "kind": "all"
      }
    },
    "runs": [
      {
        "utc": "2026-10-09T13:00:00.000Z",
        "local": "2026-10-09T09:00:00-04:00"
      },
      {
        "utc": "2026-10-12T13:00:00.000Z",
        "local": "2026-10-12T09:00:00-04:00"
      }
    ],
    "status": "count-reached",
    "startAt": "2026-10-09T12:00:00.000Z",
    "windowEnd": "2027-10-09T12:00:00.000Z"
  },
  "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
HTTP 400
{
  "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
HTTP 401
{
  "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
HTTP 403
{
  "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
HTTP 405
{
  "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
HTTP 408
{
  "ok": false,
  "code": "REQUEST_TIMEOUT",
  "message": "Request body timeout or aborted",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
413Body exceeds 1024 bytes; before admission
HTTP 413
{
  "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
HTTP 415
{
  "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
HTTP 429
{
  "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
HTTP 500
{
  "ok": false,
  "code": "OPERATION_FAILED",
  "message": "Operation failed",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
503Authentication/metering dependency unavailable
HTTP 503
{
  "ok": false,
  "code": "API_GATEWAY_UNAVAILABLE",
  "message": "API access denied",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
422INVALID_CRON_EXPRESSION: Expression cannot be parsed; details.reason explains which field; INVALID_TIME_ZONE: timeZone is not a supported IANA time zone; INVALID_START_AT: startAt is outside 1970-01-01 to 2099-01-01 or not a valid instant
HTTP 422
{
  "ok": false,
  "code": "INVALID_CRON_EXPRESSION",
  "message": "Expression cannot be parsed; details.reason explains which field",
  "request_id": "req_example",
  "timestamp": "2026-10-11T00:00:00.000Z"
}
Error handling

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.expressionstring
Normalized cron expression (macros expanded).
data.timeZonestring
IANA time zone used for wall times.
data.modestring
Day-of-month/day-of-week rule applied.
data.descriptionobject
Resource description.
data.description.minutestring
Minute field explanation.
data.description.hourstring
Hour field explanation.
data.description.dayOfMonthstring
Day-of-month field explanation.
data.description.monthstring
Month field explanation.
data.description.dayOfWeekstring
Day-of-week field explanation.
data.explanationobject
Endpoint-specific example value.
data.explanation.dialectstring
Endpoint-specific example value.
data.explanation.timeobject
Endpoint-specific example value.
data.explanation.time.kindstring
Endpoint-specific example value.
data.explanation.time.timesarray
Endpoint-specific example value.
data.explanation.daysobject
Endpoint-specific example value.
data.explanation.days.kindstring
Endpoint-specific example value.
data.explanation.days.dowobject
Endpoint-specific example value.
data.explanation.monthsobject
Endpoint-specific example value.
data.explanation.months.kindstring
Endpoint-specific example value.
data.runsarray
Upcoming runs in chronological order.
data.runs[].utcstring
Run instant in UTC (ISO 8601).
data.runs[].localstring
Run wall time with the zone offset at that instant (RFC 3339).
data.statusstring
Operation result.
data.startAtstring
Instant after which runs are listed.
data.windowEndstring
End of the search window (exclusive).
request_idstring
Origin-response identifier matching X-Request-ID; a shared HTTP cache may replay the original trace.
timestampstring
Response creation timestamp.