Concorde

Appearance

@shutter-network/concorde/scheduler ​

The HTTP routes this component serves: 4 on the Agent server.

Every path is relative. Each one is printed as the plugin declares it, under whatever prefix the component's constructor registers that plugin at. This page states no mount point, because the constructor is where the mount point is decided.

Generated from what the route plugins in src/scheduler/routes.ts declare, which is what a running Gateway serves at GET /openapi.json. Never edited by hand.

Agent server ​

The Agent server has no authentication of any kind. Everything below is reachable by the agent, and therefore by an injected prompt (ADR-0003). Nothing on it names a credential.

GET /schedules ​

List Schedules, soonest to fire first

Every live Schedule, ascending by nextFireAt so the next to fire is first. name breaks a tie. A spent or cancelled Schedule is absent, because the row is the arming. limit defaults to 50 and is capped at 200. A larger value is refused with a 400 rather than quietly reduced. There is no cursor and no offset. The Schedules past the cap are reachable only by raising the limit or narrowing the arrangement. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Schedules.

Query parameters

  • limit integer, optional, 1 to 200, default 50

Responses

200 application/json

The live Schedules, soonest fire first.

  • schedules array of object, required

    • name string, required

    • spec one of 2 shapes, required

      • Option 1: object
        • kind string, required, always "once"
        • at string, required
      • Option 2: object
        • kind string, required, always "cron"
        • expr string, required
        • tz string, required

    • data any JSON, required

      Arbitrary JSON, echoed verbatim in the fired Signal's payload. The Scheduler never interprets it, so what a Schedule carries is the creator's convention and their Signal Handler is where it is read. Omitted, it is stored as null.

    • until string or null, required

      The cron end instant if the Schedule has one, else null. Always null for a once.

    • nextFireAt string, required

      When the Schedule next fires, ISO 8601. Always present: reads answer only live Schedules, and a create that would resolve to no future fire is a 400 rather than a spent record.

400 application/json

The limit is out of range or not an integer, or a parameter this route does not take was written.

  • statusCode integer, required
  • error string, required
  • message string, required

DELETE /schedules/{name} ​

Cancel a Schedule by name

Cancel the Schedule this name addresses, and stop every future fire. 204 on success, and 404 on a name that addresses none. An unknown name is refused rather than answered an idempotent 204. So a caller learns a Schedule was already gone rather than being told it stopped nothing. This route takes no query parameters at all. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Schedules.

Path parameters

  • name string, required, matching ^[A-Za-z0-9._-]{1,128}$

Responses

204 with no body

The Schedule was cancelled; every future fire is stopped.

400 application/json

The name in the path is not a legible url-safe key of up to 128 letters, digits, dots, dashes or underscores, or a query parameter was written.

  • statusCode integer, required
  • error string, required
  • message string, required

404 application/json

No live Schedule has that name to cancel.

  • statusCode integer, required
  • error string, required
  • message string, required

GET /schedules/{name} ​

Read one Schedule by name

The live Schedule this name addresses, or a 404 when none does. A Schedule that fired out or was cancelled is gone, so this answers only what is still arranged. This route takes no query parameters at all. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Schedules.

Path parameters

  • name string, required, matching ^[A-Za-z0-9._-]{1,128}$

Responses

200 application/json

The Schedule.

  • name string, required

  • spec one of 2 shapes, required

    • Option 1: object
      • kind string, required, always "once"
      • at string, required
    • Option 2: object
      • kind string, required, always "cron"
      • expr string, required
      • tz string, required

  • data any JSON, required

    Arbitrary JSON, echoed verbatim in the fired Signal's payload. The Scheduler never interprets it, so what a Schedule carries is the creator's convention and their Signal Handler is where it is read. Omitted, it is stored as null.

  • until string or null, required

    The cron end instant if the Schedule has one, else null. Always null for a once.

  • nextFireAt string, required

    When the Schedule next fires, ISO 8601. Always present: reads answer only live Schedules, and a create that would resolve to no future fire is a 400 rather than a spent record.

400 application/json

The name in the path is not a legible url-safe key of up to 128 letters, digits, dots, dashes or underscores, or a query parameter was written.

  • statusCode integer, required
  • error string, required
  • message string, required

404 application/json

No live Schedule has that name.

  • statusCode integer, required
  • error string, required
  • message string, required

PUT /schedules/{name} ​

Create or update a Schedule by name

Create-or-update the Schedule this name addresses. An upsert, so a retry or a revised plan converges to one Schedule rather than a duplicate. Answers 201 when the name was new and 200 when it already existed, each with the resulting read model. There is no 404, since a PUT on an absent name creates it. The name is the sole identifier and comes from the path.

A create that could never fire is a 400 rather than a stored Schedule that never fires. That covers a once already past, and a cron whose until sits at or before its next occurrence. This route takes no query parameters at all. An unknown query parameter is a 400, not a filter that did nothing and a request answered with everything.

Tagged Schedules.

Path parameters

  • name string, required, matching ^[A-Za-z0-9._-]{1,128}$

Request body

application/json, required.

  • spec one of 2 shapes, required

    • Option 1: object

      • kind string, required, always "once"

      • at string, required

        The single absolute instant to fire at, ISO 8601. Refused as a 400 if malformed or already past.

    • Option 2: object

      • kind string, required, always "cron"

      • expr string, required

        A cron expression, parsed by cron-parser. A malformed one is a 400.

      • tz string, optional

        The IANA time zone the expression is evaluated in. Omitted, it is UTC. An unknown zone is a 400.

  • data any JSON, optional

    Arbitrary JSON, echoed verbatim in the fired Signal's payload. The Scheduler never interprets it, so what a Schedule carries is the creator's convention and their Signal Handler is where it is read. Omitted, it is stored as null.

  • until string, optional

    A cron Schedule's optional end instant, ISO 8601: after its last occurrence at or before this, the Schedule is retired. Meaningless for a once, which bounds itself by firing once, so a once carrying one is a 400.

Responses

200 application/json

The Schedule as it now stands, updated.

  • name string, required

  • spec one of 2 shapes, required

    • Option 1: object
      • kind string, required, always "once"
      • at string, required
    • Option 2: object
      • kind string, required, always "cron"
      • expr string, required
      • tz string, required

  • data any JSON, required

    Arbitrary JSON, echoed verbatim in the fired Signal's payload. The Scheduler never interprets it, so what a Schedule carries is the creator's convention and their Signal Handler is where it is read. Omitted, it is stored as null.

  • until string or null, required

    The cron end instant if the Schedule has one, else null. Always null for a once.

  • nextFireAt string, required

    When the Schedule next fires, ISO 8601. Always present: reads answer only live Schedules, and a create that would resolve to no future fire is a 400 rather than a spent record.

201 application/json

The Schedule as created.

  • name string, required

  • spec one of 2 shapes, required

    • Option 1: object
      • kind string, required, always "once"
      • at string, required
    • Option 2: object
      • kind string, required, always "cron"
      • expr string, required
      • tz string, required

  • data any JSON, required

    Arbitrary JSON, echoed verbatim in the fired Signal's payload. The Scheduler never interprets it, so what a Schedule carries is the creator's convention and their Signal Handler is where it is read. Omitted, it is stored as null.

  • until string or null, required

    The cron end instant if the Schedule has one, else null. Always null for a once.

  • nextFireAt string, required

    When the Schedule next fires, ISO 8601. Always present: reads answer only live Schedules, and a create that would resolve to no future fire is a 400 rather than a spent record.

400 application/json

The path name is malformed, a query parameter was written, an unknown field or an unknown kind was sent, a once carried a cron-only until, the cron expr is invalid or its tz unknown, or the at/until is malformed or the once instant already past.

  • statusCode integer, required
  • error string, required
  • message string, required