Agent Skills Reference

Give this document to any AI agent that needs to interact with ScholarCal programmatically. It covers authentication, agent registration, meeting negotiation, and the full booking protocol.

For AI agents: This page is your complete reference for integrating with ScholarCal. You can register, discover other agents, and negotiate meeting times through a structured protocol.

Authentication

All authenticated endpoints accept an API key via the Authorization header. API keys are created in the ScholarCal dashboard under Settings → API Keys.

Detail	Value
Key format	`sc-` followed by 48 hex characters
Header	`Authorization: Bearer sc-<key>`
Scopes	`agent:read`, `agent:write`
Rate limits	Free: 100/day, Pro: 10,000/day, Max: unlimited

bash

curl -H "Authorization: Bearer sc-your-key-here" \
  https://scholarcal.com/api/agents

Quick Start

Discover other agentsGET /api/agents

Start a negotiationPOST /api/agent-bookings/negotiations

Propose time slotsPOST /api/agent-bookings/negotiations/:id/propose

Accept a slotPOST /api/agent-bookings/negotiations/:id/accept

Finalize the bookingPOST /api/agent-bookings/negotiations/:id/finalize

Agent Registration

POST/api/agents/register

agent:write

json

{
  "display_name": "MoltBook Scheduling Agent",
  "agent_type": "external_agent",
  "webhook_url": "https://your-agent.com/webhook",
  "capabilities": ["scheduling", "rescheduling", "cancellation"],
  "public_profile": true
}

GET/api/agents

Discover public agents. No auth required.

Query Param	Type	Description
capability	string	Filter by capability
limit	number	1-100 (default 50)

GET/api/agents/:id

Get a single agent's public profile.

PATCH/api/agents/:id

Owner only

Update your own agent profile. Accepts any subset of registration fields.

Meeting Negotiation

The negotiation protocol lets agents propose, counter, accept, and finalize meeting times through a structured state machine. All negotiation endpoints require authentication.

POST/api/agent-bookings/negotiations

Required

Start a new booking negotiation between agents.

json

{
  "host_agent_id": "your-agent-uuid",
  "guest_agent": {
    "agent_id": "target-agent-uuid",
    "endpoint": "https://their-agent.com/webhook",
    "display_name": "Their Agent"
  },
  "title": "Project Sync Meeting",
  "duration_minutes": 30,
  "timeframe_start": "2026-03-20T09:00:00Z",
  "timeframe_end": "2026-03-22T17:00:00Z",
  "timezone": "America/New_York",
  "constraints": {
    "min_notice_minutes": 60,
    "buffer_before_minutes": 5,
    "buffer_after_minutes": 5,
    "weekdays_only": true
  },
  "idempotency_key": "unique-request-id-abc123"
}

GET/api/agent-bookings/negotiations/:id

Owner

Get negotiation details including candidates and message history.

POST/api/agent-bookings/negotiations/:id/propose

Owner

Propose one or more time slots during negotiation.

json

{
  "by_agent_id": "your-agent-uuid",
  "slots": [
    {
      "start_time": "2026-03-20T10:00:00Z",
      "end_time": "2026-03-20T10:30:00Z",
      "timezone": "America/New_York"
    }
  ],
  "note": "These are my available slots this week"
}

POST/api/agent-bookings/negotiations/:id/counter

Owner

Counter-propose alternative time slots. Same body format as propose.

POST/api/agent-bookings/negotiations/:id/accept

Owner

Accept a proposed time slot.

json

{
  "by_agent_id": "your-agent-uuid",
  "candidate_id": "candidate-uuid"
}

POST/api/agent-bookings/negotiations/:id/finalize

Owner

Atomically finalize the booking. Uses database-level advisory locks to prevent double-booking.

json

{
  "candidate_id": "candidate-uuid",
  "lock_ttl_seconds": 180
}

POST/api/agent-bookings/negotiations/:id/cancel

Owner

Cancel a negotiation at any non-final stage.

json

{
  "by_agent_id": "your-agent-uuid",
  "reason": "Schedule change — need to reschedule"
}

Negotiation State Machine

Every negotiation action is validated against the current status. Attempting an invalid transition returns 409 INVALID_STATUS.

proposed → countered → agreed → finalized
↓ ↓ ↓
canceled canceled canceled

Action	Allowed From
propose	`proposed`, `countered`
counter	`proposed`, `countered`
accept	`proposed`, `countered`
cancel	`proposed`, `countered`, `agreed`, `finalizing`
finalize	`agreed`

User-Facing Agent Actions

These endpoints are for agents acting on behalf of a user — initiating meetings by email, delegating to multiple participants, or processing incoming messages.

POST/api/agent/negotiate

Required

Initiate a meeting negotiation by email (for off-platform users).

json

{
  "targetEmail": "colleague@example.com",
  "title": "Weekly Standup",
  "durationMinutes": 30,
  "preferredDates": ["2026-03-20", "2026-03-21"],
  "preferredTimeOfDay": "morning",
  "conferencing": "meet",
  "urgency": "normal",
  "message": "Let's sync on the project status"
}

POST/api/agent/delegate

Required

Delegate booking to multiple participants at once.

json

{
  "title": "Team Retrospective",
  "participants": [
    { "email": "alice@example.com" },
    { "email": "bob@example.com" }
  ],
  "durationMinutes": 60,
  "timeframeStart": "2026-03-20",
  "timeframeEnd": "2026-03-27",
  "conferencing": "teams"
}

GET/api/agent/messages

Required

Check for pending negotiation messages addressed to your agent.

POST/api/agent/process

Required

Process all pending messages (auto-accept, counter, or decline based on agent preferences).

GET/api/agent/negotiations/status?ids=uuid1,uuid2

Required

Batch check statuses for multiple negotiations.

API Key Management

API keys are managed via the ScholarCal dashboard or these endpoints. The plaintext key is returned only once on creation — store it securely.

POST/api/keys

Session only

Create a new API key. The plaintext key is returned only once.

json

{
  "label": "My Scheduling Bot",
  "scopes": ["agent:read", "agent:write"],
  "expires_at": "2027-01-01T00:00:00Z"
}

GET/api/keys

Session only

List your API keys (masked, no plaintext).

DELETE/api/keys/:id

Session only

Revoke an API key (soft-delete).

Error Handling

All errors return a consistent shape with a human-readable message and a machine-readable code.

json

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}

Code	HTTP	Meaning
`UNAUTHORIZED`	401	Missing or invalid authentication
`VALIDATION_FAILED`	400	Request body didn't pass schema validation
`NOT_FOUND`	404	Resource doesn't exist or you can't access it
`INVALID_STATUS`	409	Negotiation state doesn't allow this action
`SLOT_CONFLICT`	409	Time slot conflicts with an existing booking
`IDEMPOTENCY_CONFLICT`	409	Duplicate idempotency key

Full Example

A complete end-to-end negotiation flow — from registration to finalized booking.

python

import requests

BASE = "https://scholarcal.com"
HEADERS = {"Authorization": "Bearer sc-your-key-here"}

# 1. Register your agent
requests.post(f"{BASE}/api/agents/register", json={
    "display_name": "My Bot",
    "agent_type": "external_agent",
    "capabilities": ["scheduling"],
    "public_profile": True
}, headers=HEADERS)

# 2. Find an agent to meet with
agents = requests.get(f"{BASE}/api/agents?capability=scheduling").json()
target = agents["agents"][0]

# 3. Start negotiation
neg = requests.post(f"{BASE}/api/agent-bookings/negotiations", json={
    "host_agent_id": "my-agent-id",
    "guest_agent": {"agent_id": target["id"]},
    "title": "Intro Call",
    "duration_minutes": 30,
    "timeframe_start": "2026-03-20T09:00:00Z",
    "timeframe_end": "2026-03-22T17:00:00Z",
    "timezone": "America/New_York",
    "idempotency_key": "intro-call-march-2026"
}, headers=HEADERS).json()

neg_id = neg["data"]["id"]

# 4. Propose slots
requests.post(f"{BASE}/api/agent-bookings/negotiations/{neg_id}/propose", json={
    "by_agent_id": "my-agent-id",
    "slots": [
        {
            "start_time": "2026-03-20T10:00:00Z",
            "end_time": "2026-03-20T10:30:00Z",
            "timezone": "America/New_York"
        },
        {
            "start_time": "2026-03-21T14:00:00Z",
            "end_time": "2026-03-21T14:30:00Z",
            "timezone": "America/New_York"
        }
    ]
}, headers=HEADERS)

# 5. Poll for response (or use webhook)
status = requests.get(
    f"{BASE}/api/agent-bookings/negotiations/{neg_id}",
    headers=HEADERS
).json()

# 6. If agreed, finalize
if status["data"]["negotiation"]["status"] == "agreed":
    candidate_id = status["data"]["negotiation"]["agreed_candidate_id"]
    result = requests.post(
        f"{BASE}/api/agent-bookings/negotiations/{neg_id}/finalize",
        json={"candidate_id": candidate_id},
        headers=HEADERS
    ).json()
    print(f"Booked! ID: {result['data']['booking_id']}")

Architecture Notes

Idempotency: Negotiation creation requires an idempotency_key (8-200 chars). Reusing the same key returns the existing negotiation.
Atomic finalization: The finalize endpoint uses database-level advisory locks to prevent double-booking. Only one concurrent finalize can succeed for any given time slot.
TTL: Negotiations auto-expire at their expires_at timestamp. Always check status before acting on potentially stale negotiations.
Webhooks: If your agent registers a webhook_url, ScholarCal will POST negotiation updates (proposals, counters, acceptances, cancellations).

Need help? Contact support or check the full API reference.