Scheduling proposals

Scheduling proposals let an organizer agent offer a set of candidate time slots to one or more participant agents, collect their responses, and resolve the proposal into a confirmed event once there’s enough agreement.

A proposal moves through these states:

pending — awaiting participant responses
confirmed — resolved; a winning slot was picked and an event created
expired — TTL passed without resolution
cancelled — cancelled by the organizer or auto-cancelled because all participants declined

Lifecycle at a glance

sequenceDiagram
    participant Org as Organizer agent
    participant API as Chronary API
    participant P as Participant agent(s)
    participant WH as Webhook subscribers

    Org->>API: POST /v1/scheduling/proposals
    API-->>WH: proposal.created
    API-->>Org: 201 { id: spr_..., status: pending }

    P->>API: POST /v1/scheduling/proposals/:id/respond
    API-->>WH: proposal.responded

    Note over API: When every participant has responded, or the organizer calls resolve
    API->>API: pickBestSlot() + create event
    API-->>WH: proposal.confirmed

    Note over API,WH: Alternate terminal states
    API-->>WH: proposal.cancelled (organizer cancel or all_declined)
    API-->>WH: proposal.expired (expires_at passed)

For a code-heavy walkthrough, see the multi-agent scheduling and negotiation guide.

Create a proposal

POST /v1/scheduling/proposals

Request body

| Field | Type | Required | Description | |-------|------|----------|-------------| | title | string | Yes | Human-readable title (max 500 chars) | | description | string | No | Optional details (max 5000 chars) | | organizer_agent_id | string | Yes | Agent ID of the proposal organizer | | participant_agent_ids | string[] | Yes | 1–50 participant agent IDs | | calendar_id | string | Yes | Default target calendar for the resolved event | | slots | object[] | Yes | 1–20 candidate slots (see below) | | expires_at | string | No | ISO timestamp — proposal auto-expires if unresolved | | metadata | object | No | Arbitrary JSON, max 16 KB |

Each slot is:

| Field | Type | Required | Description | |-------|------|----------|-------------| | start_time | string | Yes | ISO datetime | | end_time | string | Yes | ISO datetime | | weight | number | No | Organizer preference, 0–10 (default 1.0) | | calendar_id | string | No | Override target calendar for this specific slot |

Example

curl -X POST https://api.chronary.ai/v1/scheduling/proposals \
  -H "Authorization: Bearer chr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q2 planning sync",
    "organizer_agent_id": "agt_organizer",
    "participant_agent_ids": ["agt_alice", "agt_bob"],
    "calendar_id": "cal_team",
    "slots": [
      { "start_time": "2026-04-20T14:00:00Z", "end_time": "2026-04-20T15:00:00Z", "weight": 2.0 },
      { "start_time": "2026-04-21T14:00:00Z", "end_time": "2026-04-21T15:00:00Z" }
    ],
    "expires_at": "2026-04-19T00:00:00Z"
  }'

from chronary import Chronary

client = Chronary()

proposal = client.scheduling.create(
    title="Q2 planning sync",
    organizer_agent_id="agt_organizer",
    participant_agent_ids=["agt_alice", "agt_bob"],
    calendar_id="cal_team",
    slots=[
        {"start_time": "2026-04-20T14:00:00Z", "end_time": "2026-04-20T15:00:00Z", "weight": 2.0},
        {"start_time": "2026-04-21T14:00:00Z", "end_time": "2026-04-21T15:00:00Z"},
    ],
    expires_at="2026-04-19T00:00:00Z",
)
print(proposal.id)  # "spr_..."

import Chronary from '@chronary/sdk';

const client = new Chronary();

const proposal = await client.scheduling.create({
  title: 'Q2 planning sync',
  organizer_agent_id: 'agt_organizer',
  participant_agent_ids: ['agt_alice', 'agt_bob'],
  calendar_id: 'cal_team',
  slots: [
    { start_time: '2026-04-20T14:00:00Z', end_time: '2026-04-20T15:00:00Z', weight: 2.0 },
    { start_time: '2026-04-21T14:00:00Z', end_time: '2026-04-21T15:00:00Z' },
  ],
  expires_at: '2026-04-19T00:00:00Z',
});

Response `201 Created`

Returns the proposal summary (full object without nested slots/responses):

{
  "id": "spr_a1b2c3",
  "title": "Q2 planning sync",
  "organizer_agent_id": "agt_organizer",
  "participant_agent_ids": ["agt_alice", "agt_bob"],
  "calendar_id": "cal_team",
  "status": "pending",
  "expires_at": "2026-04-19T00:00:00Z",
  "metadata": {},
  "created_at": "2026-04-16T12:00:00Z",
  "updated_at": "2026-04-16T12:00:00Z"
}

Errors

| Status | Type | Cause | |--------|------|-------| | 400 | validation | Invalid slot times, empty participants, or malformed payload | | 404 | not_found | Organizer or participant agent not found | | 429 | quota_exceeded | Monthly proposal quota reached |

List proposals

GET /v1/scheduling/proposals

Query parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | status | string | — | Filter by pending, confirmed, expired, or cancelled | | organizer_agent_id | string | — | Filter by organizer | | limit | integer | 50 | 1–200 | | offset | integer | 0 | Pagination offset |

Get a proposal

GET /v1/scheduling/proposals/:id

Returns the full proposal including slots and responses arrays.

Errors

| Status | Type | Cause | |--------|------|-------| | 404 | not_found | Proposal not found |

Respond to a proposal

POST /v1/scheduling/proposals/:id/respond

Request body

| Field | Type | Required | Description | |-------|------|----------|-------------| | agent_id | string | Yes | The responding participant | | response | string | Yes | accept, decline, or counter | | selected_slot_id | string | If accept | ID of the slot the agent is accepting | | counter_slots | object[] | No | Up to 20 alternative slots (informational when countering) | | message | string | No | Up to 2000 chars |

Each participant may respond at most once per proposal. Subsequent responses return 409 conflict with type duplicate_response.

Example

curl -X POST https://api.chronary.ai/v1/scheduling/proposals/spr_a1b2c3/respond \
  -H "Authorization: Bearer chr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_alice",
    "response": "accept",
    "selected_slot_id": "slt_x7"
  }'

client.scheduling.respond(
    "spr_a1b2c3",
    agent_id="agt_alice",
    response="accept",
    selected_slot_id="slt_x7",
)

await client.scheduling.respond('spr_a1b2c3', {
  agent_id: 'agt_alice',
  response: 'accept',
  selected_slot_id: 'slt_x7',
});

Errors

| Status | Type | Cause | |--------|------|-------| | 400 | validation | Missing selected_slot_id when accepting | | 403 | forbidden | Agent is not a participant | | 404 | not_found | Proposal or agent not found | | 409 | conflict | Proposal is not in pending state | | 409 | conflict | Agent has already responded |

Resolve a proposal

POST /v1/scheduling/proposals/:id/resolve

Picks the winning slot using organizer preference weights plus participant acceptances, creates an event on the proposal’s calendar_id, and marks the proposal confirmed. If every participant has declined, the proposal is marked cancelled instead.

Response `200 OK`

When confirmed:

{
  "status": "confirmed",
  "resolved_slot": {
    "id": "slt_x7",
    "start_time": "2026-04-20T14:00:00Z",
    "end_time": "2026-04-20T15:00:00Z",
    "weight": 2.0,
    "calendar_id": null
  }
}

When all participants declined:

{ "status": "cancelled", "reason": "all_declined" }

Errors

| Status | Type | Cause | |--------|------|-------| | 404 | not_found | Proposal not found | | 409 | conflict | Proposal is not in pending state |

Auto-resolution

When the last pending response arrives via POST /respond, Chronary runs the same resolution logic as an explicit POST /resolve call — the organizer does not need to resolve manually. The scoring rule is additive: score = slot.weight + Σ(response_scores), with accept = 1.0, counter = 0.3, decline = 0.0. Ties break by earliest start_time. If every response is a decline, the proposal is cancelled with reason all_declined instead of confirmed.

Cancel a proposal

POST /v1/scheduling/proposals/:id/cancel

Cancels a pending proposal. Cannot be undone.

Response `200 OK`

{ "status": "cancelled" }

Errors

| Status | Type | Cause | |--------|------|-------| | 404 | not_found | Proposal not found | | 409 | conflict | Proposal is not in pending state |

Webhook events

Subscribe to these webhook types to receive push notifications for proposal lifecycle transitions. See the webhooks guide for signature verification and retry behavior.

| Type | Fired when | Payload | |------|-----------|---------| | proposal.created | POST /v1/scheduling/proposals succeeds | Full proposal summary | | proposal.responded | A participant calls POST /:id/respond | proposal_id, agent_id, response | | proposal.confirmed | Resolution picks a winning slot (via auto-resolve or explicit POST /:id/resolve) | proposal_id, resolved_slot, created_event_id | | proposal.cancelled | Organizer calls POST /:id/cancel, or every response was decline | proposal_id, reason (organizer_cancelled or all_declined) | | proposal.expired | expires_at passed without resolution | proposal_id |

Scheduling proposals

Lifecycle at a glance

Create a proposal

Request body

Example

Response 201 Created

Errors

List proposals

Query parameters

Get a proposal

Errors

Respond to a proposal

Request body

Example

Errors

Resolve a proposal

Response 200 OK

Errors

Auto-resolution

Cancel a proposal

Response 200 OK

Errors

Webhook events

Response `201 Created`

Response `200 OK`

Response `200 OK`