6.2.2 Developer Guide — APIs — Planner API — Scheduling Endpoints

The Planner API provides programmatic access to create, manage, and observe scheduled actions across the platform. It is designed for predictability, idempotency, and auditability, enabling external systems and internal services to coordinate time-based workflows.

API Scope and Guarantees

The Planner API supports scheduling and inspection of planned actions. Execution is handled asynchronously by the platform scheduler.

Guarantees:

Deterministic scheduling semantics

Idempotent create and update operations

Explicit execution state tracking

The API does not expose internal job runners.

Endpoint Structure

Endpoints are resource-oriented and versioned.

Typical endpoints:

/api/v1/plans

/api/v1/plans/{id}

/api/v1/plans/{id}/runs

Creating Schedules

Schedules define when and how an action should execute. Requests must be idempotent to prevent duplicate plans.

Schedule attributes:

Target action and payload

Execution time or recurrence rule

Timezone

Activation state

Example create request:

POST /api/v1/plans { "action": "content.publish", "execute_at": "2025-02-01T09:00:00Z", "timezone": "Europe/Amsterdam", "payload": {"content_id":"uuid"} }

Recurrence Rules

Recurring schedules use explicit recurrence definitions.

Supported patterns:

Cron-like expressions

Fixed intervals

Calendar-based rules

Recurrence rules are validated before persistence.

Updating and Cancelling

Schedules may be updated or cancelled prior to execution. Updates preserve audit history and do not mutate completed runs.

Example cancellation:

DELETE /api/v1/plans/{id}

Execution and Runs

Each execution produces a run record with explicit status.

Run states:

Pending

Executing

Completed

Failed

Run history is immutable and queryable.

Idempotency and Concurrency

Create and update operations support idempotency keys to prevent duplicates during retries.

Example idempotency:

Idempotency-Key: 9f3a-uuid

Error Handling

Errors are returned deterministically with stable codes. Scheduling failures do not affect existing plans.

Security and Isolation

Planner API access is authenticated and tenant-scoped. Scheduled actions execute within the originating tenant and organization context. Rate limiting and permission checks are enforced on all endpoints.