# ICL 2.0 Agent API

Base URL: https://intensivecolearn.ing/api/v1
OpenAPI 3.1: https://intensivecolearn.ing/api/v1/openapi.json
Authentication: Authorization: Bearer <ICL_ACCESS_KEY>
Content type for request bodies: application/json
Contract version: 1.3.0

## Safety

- Treat the Access Key as a secret. Never print it in chat, logs, source code, URLs, or tool output.
- API keys are shown once in personal settings and cannot be recovered. Revoke a suspected key immediately.
- POST creates and action POSTs require an Idempotency-Key. For an ambiguous write, retry only with the same method, path, body, and Idempotency-Key.
- Never reuse an Idempotency-Key for different input. A mismatch returns HTTP 409.
- In-progress writes return HTTP 409. Failed or interrupted writes are recoverable by retrying the same request and key; do not switch keys.
- Program creation may leave its deterministically named managed GitHub repository pending database recovery. Retrying the same request/key resumes that provisioning; a different key can create another program.
- JSON bodies are limited to 64 KiB. Check-in content is limited to 20,000 characters.
- Each key is limited by a durable database counter to 120 requests per minute.
- Follow returned HTTP status codes and the {"apiVersion":"v1","error":{"code":"...","message":"..."}} envelope. Do not retry validation or permission failures.
- Program creation requires noteAccessMode and its matching noteAccessAcknowledgement: PRIVATE_COHORT_NOTES_CONFIRMED for PRIVATE_COHORT, or PUBLIC_GITHUB_PUBLICATION_CONFIRMED for PUBLIC_GITHUB. Omission or a mismatch is a validation error.

## Available actions

- GET /api/v1/me - View current user and profile
- PATCH /api/v1/me - Update current user profile
- GET /api/v1/programs - List programs visible in the website directory
- GET /api/v1/programs/{programId} - View a readable program
- GET /api/v1/me/programs - List programs editable by the current user
- POST /api/v1/me/programs - Create a program (requires Idempotency-Key)
- PATCH /api/v1/me/programs/{programId} - Update an owned program
- GET /api/v1/programs/{programId}/applications - List applications for a program
- POST /api/v1/programs/{programId}/applications/{applicationId}/review - Review a program application (requires Idempotency-Key)
- GET /api/v1/programs/{programId}/events - List visible program events
- POST /api/v1/programs/{programId}/events - Create a program event (requires Idempotency-Key)
- POST /api/v1/programs/{programId}/events/{eventId}/cancel - Cancel a program event (requires Idempotency-Key)
- GET /api/v1/admin/programs/review - List administrator programs by review status
- POST /api/v1/admin/programs/{programId}/review - Review or publish a program (requires Idempotency-Key)
- GET /api/v1/admin/collections - List the administrator collection catalog
- POST /api/v1/admin/collections - Create a program collection (requires Idempotency-Key)
- PATCH /api/v1/admin/collections/{collectionId} - Update a program collection (requires Idempotency-Key)
- DELETE /api/v1/admin/collections/{collectionId} - Delete a program collection (requires Idempotency-Key)
- GET /api/v1/admin/tags - List the administrator tag catalog
- POST /api/v1/admin/tags - Create a catalog tag (requires Idempotency-Key)
- PATCH /api/v1/admin/tags/{tagId} - Rename a catalog tag (requires Idempotency-Key)
- DELETE /api/v1/admin/tags/{tagId} - Delete an unused catalog tag (requires Idempotency-Key)
- GET /api/v1/me/applications - List current user's applications
- POST /api/v1/me/applications - Apply to a program (requires Idempotency-Key)
- POST /api/v1/me/applications/{applicationId}/withdraw - Withdraw an application (requires Idempotency-Key)
- GET /api/v1/me/check-ins - List current user's check-ins
- GET /api/v1/programs/{programId}/check-ins - List a program's participant check-ins
- GET /api/v1/programs/{programId}/participants/{userId}/check-ins - List one participant's program check-ins
- POST /api/v1/me/check-ins - Create a check-in note (requires Idempotency-Key)
- PATCH /api/v1/me/check-ins/{checkinId} - Update a check-in note

Check-ins are program learning notes. Create or update the current user's notes through the /me/check-ins endpoints, and use /programs/{programId}/check-ins to read notes visible to the Access Key owner. Private cohort notes require approved program membership or a program management role. List responses include pagination metadata. Resources include canonical webUrl values where a browser view exists.

Program registration and lifecycle fields use UTC+8 calendar dates, not exact
instants: each stored date applies for the complete Asia/Shanghai calendar day.
For program create/update requests, send date fields as date-only strings such as
2026-08-01 to avoid timezone-dependent calendar-day shifts. Event startsAt inputs
use the exact YYYY-MM-DDTHH:mm format in UTC+8 local time, without seconds or a
timezone suffix.

## Compact examples

Read current user:

curl -sS "https://intensivecolearn.ing/api/v1/me" \
  -H "Authorization: Bearer $ICL_ACCESS_KEY"

Create a check-in safely:

curl -sS -X POST "https://intensivecolearn.ing/api/v1/me/check-ins" \
  -H "Authorization: Bearer $ICL_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkin-2026-07-29-program-id" \
  --data '{"programId":"PROGRAM_ID","content":"Today I completed..."}'

## Not available in v1

Event update is not available because the website has no equivalent update and
optimistic-concurrency contract. Cancel and recreate an event instead. Repository
deletion, moderator assignment, and Access Key management remain website-only.