Skip to main content
Schedules

Archive schedules in bulk

Archive up to 50 Forward Schedules by explicit ID.

POST /api/v1/forward/schedules/archive Archives Schedules without physically deleting Schedules or Schedule Runs. Only PATs and administrator SATs may call this endpoint. Identity-bound SATs cannot archive schedules in bulk.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or administrator SAT>
Content-TypeYesapplication/json
Idempotency-KeyNoOptional idempotency key. Requests with the same owner, path, and body can be replayed safely.

Request body

ParameterTypeRequiredDescription
schedule_idsarray<string>YesAfter deduplication, 1–50 non-empty Schedule IDs.
The request body uses strict JSON field validation. Unknown fields or a trailing second JSON value return 400 invalid_request_body.

Example request

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/schedules/archive' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: archive-schedules-20260821" \
  -d '{
    "schedule_ids": [
      "sched_019f00112233445566778899aabbccdd",
      "sched_019f00112233445566778899aabbccee"
    ]
  }'

Archive all schedules for an Identity or owner

The endpoint does not provide an unbounded synchronous operation for an entire Identity or owner. First list the target records with GET /api/v1/forward/schedules?identity_id=<id>&limit=100, or omit identity_id for the current owner. Continue pagination by passing last_id as after_id, confirm the targets, and submit IDs in batches of at most 50. Use a separate Idempotency-Key for each batch. Each batch is atomic, but multiple batches are not. If new Schedules might be created during cleanup, query again from the first page after each pass until no targets remain.

Example response

{
  "archived_count": 2
}
archived_count is the number of Schedules changed from unarchived to archived. Already archived targets are not counted again.

Archive semantics

  • Both active and paused Schedules can be archived. Archiving sets archived_at, clears the next scheduled run time, and prevents new Runs.
  • The server resolves all IDs within the current owner before changing any record. If any ID does not exist or belongs to another owner, the whole batch returns 404 without identifying the failed ID.
  • An already archived ID is an idempotent no-op. If every target is already archived, the response is archived_count: 0.
  • Existing pending or running Runs do not block archiving and are not canceled, skipped, terminated, changed, or deleted.
  • Archived Schedules remain retrievable by ID and appear in lists with include_archived=true. Historical Schedule Runs remain queryable.
  • Without Idempotency-Key, repeated requests remain naturally idempotent. Reusing the same key with the same body replays the first response with Idempotency-Replayed: true.
  • Forward provides neither DELETE /api/v1/forward/schedules nor physical deletion of Schedules or Schedule Runs.

Errors

HTTPTypeCodeTrigger
400invalid_request_errorinvalid_request_bodyInvalid JSON, unknown fields such as scope or identity_id, or a trailing JSON value.
400invalid_request_errorinvalid_requestAn ID is empty or the deduplicated count is outside 1–50.
401authentication_errorauthentication_requiredPAT or SAT invalid or expired.
403permission_erroridentity_mismatchAn Identity-bound SAT calls this administrator endpoint.
404not_found_errorschedule_not_foundA Schedule does not exist or belongs to another owner.
409conflict_erroridempotency_key_reusedThe same Idempotency-Key is reused with a different body.

Archive a schedule

List schedules

List schedule runs

First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference