# AgentCal > AgentCal developer documentation: give your AI agent a real calendar of its own. Plain JSON API, agent-readable docs, live calendars for humans to follow. ## Docs - [Quickstart for agents](https://docs.youragentcal.com/agent-quickstart.md): Mint an identity, create a calendar, add events: three requests, one Bearer token. - [Approve or deny an access request](https://docs.youragentcal.com/api-reference/access-requests/approve-or-deny-an-access-request.md): Owner action (scope grants:manage). Approval creates the grant. - [List access requests](https://docs.youragentcal.com/api-reference/access-requests/list-access-requests.md): Owner only (scope grants:manage). - [Request access to a calendar](https://docs.youragentcal.com/api-reference/access-requests/request-access-to-a-calendar.md): Ask the owners for a role on a calendar you can see but not touch. One pending request per calendar; repeats return the original. Requires scope calendar:read. - [Create a calendar](https://docs.youragentcal.com/api-reference/calendars/create-a-calendar.md): One calendar per context is the intended shape (a project, a workstream, a launch). The caller becomes its first owner. Requires scope calendar:write. - [Update calendar settings](https://docs.youragentcal.com/api-reference/calendars/update-calendar-settings.md): Partial update. JSON null clears nullable fields (purpose, default_view; views: null or [] means all lenses). Renaming the slug keeps every old slug 308-redirecting forever; a taken slug returns 409 slug_taken with error.details.available suggestions. - [Create an event](https://docs.youragentcal.com/api-reference/events/create-an-event.md): Three schedule kinds: one-off (date), recurring (recur), or someday (neither; a milestone without a date yet). Requires scope calendar:write and a writer/owner grant. - [Delete an event](https://docs.youragentcal.com/api-reference/events/delete-an-event.md) - [Get one event](https://docs.youragentcal.com/api-reference/events/get-one-event.md) - [List events](https://docs.youragentcal.com/api-reference/events/list-events.md): Public for public and unlisted calendars (no auth needed); private calendars require a live grant. - [Update an event](https://docs.youragentcal.com/api-reference/events/update-an-event.md): Partial update; JSON null clears a field (date, recur, start_time clears both times, notes, category, art). Sending recur clears date and vice versa, so schedule kinds swap cleanly. - [Grant access to another agent](https://docs.youragentcal.com/api-reference/grants/grant-access-to-another-agent.md): One live grant per (calendar, agent); posting a new role replaces the old one. Demoting the last owner fails with 400 last_owner. Requires scope grants:manage. - [List grants](https://docs.youragentcal.com/api-reference/grants/list-grants.md): Owner only (scope grants:manage). Includes revoked grants as history. - [Revoke a grant](https://docs.youragentcal.com/api-reference/grants/revoke-a-grant.md): Tombstones the grant (history survives). Revoking the last owner fails with 400 last_owner. - [List credentials](https://docs.youragentcal.com/api-reference/identity/list-credentials.md): Metadata for every credential of this agent (never the secrets). Requires scope agent:read. - [Mint an additional credential](https://docs.youragentcal.com/api-reference/identity/mint-an-additional-credential.md): A second key for the same agent (e.g. one per machine). New keys carry agent:read, calendar:read, calendar:write (not grants:manage). The secret appears only in this response. - [Mint an agent identity and first calendar](https://docs.youragentcal.com/api-reference/identity/mint-an-agent-identity-and-first-calendar.md): Public, no auth. Returns the agent token once; store it. Anonymous mints also return a single-use claim_url (7 days) a human can open to link the agent to their account. With an onboard_token (from a signed-in human's Get Started flow) the agent is linked immediately. - [Revoke a credential](https://docs.youragentcal.com/api-reference/identity/revoke-a-credential.md): Revokes one key. The last active key cannot be revoked (409 last_credential). - [Who am I](https://docs.youragentcal.com/api-reference/identity/who-am-i.md): The authenticated agent, its credential, and every calendar it can touch (with roles and purpose previews). Requires scope agent:read. - [API introduction](https://docs.youragentcal.com/api-reference/introduction.md): Base URL, authentication, idempotency, and errors. Plain JSON over HTTPS; no SDK required. - [Attach a calendar as a layer](https://docs.youragentcal.com/api-reference/layers/attach-a-calendar-as-a-layer.md): Compose a project calendar from context calendars. Requires owner on this calendar plus read access to the layer. Re-posting the same pair returns the existing link; a new key renames it. Max 20 layers; no nesting (400 layer_depth); key collisions return 409 key_taken. - [Detach a layer](https://docs.youragentcal.com/api-reference/layers/detach-a-layer.md): Removes the link only; the attached calendar itself is untouched. - [List layers](https://docs.youragentcal.com/api-reference/layers/list-layers.md): Public like an events read; each attached calendar appears only if the viewer could read it directly. - [Create a share view](https://docs.youragentcal.com/api-reference/share-views/create-a-share-view.md): A filtered projection of the calendar at /v/{slug}. Omit slug for an unguessable one (a capability URL); the page never reveals which calendar it comes from. Requires scope calendar:write. - [List share views](https://docs.youragentcal.com/api-reference/share-views/list-share-views.md): Owner only (scope calendar:write). Includes revoked views as history. - [Revoke a share view](https://docs.youragentcal.com/api-reference/share-views/revoke-a-share-view.md): Tombstones the view; its /v/{slug} URL 404s afterward. - [Update a share view](https://docs.youragentcal.com/api-reference/share-views/update-a-share-view.md): name, filter, display are updatable; filter and display replace the whole object. The slug is immutable. - [Calendars](https://docs.youragentcal.com/concepts/calendars.md): One calendar per context: a project, a workstream, a launch. Slugs, timezones, visibility, and purpose. - [Events](https://docs.youragentcal.com/concepts/events.md): One-off, recurring, and someday events. Times are optional; milestones can exist before their dates do. - [Grants and access requests](https://docs.youragentcal.com/concepts/grants.md): Per-calendar access for agents: owner, writer, reader. Owners grant; strangers request. - [Humans and linking](https://docs.youragentcal.com/concepts/humans.md): How a human ends up owning what the agent minted: onboard tokens, claim links, and the dashboard. - [Layers](https://docs.youragentcal.com/concepts/layers.md): Compose a project calendar from context calendars. A layer is an attached calendar with a stable key. - [Lenses and share views](https://docs.youragentcal.com/concepts/views.md): Month, week, schedule, timeline: one calendar, several ways to read it. Share views are filtered capability URLs. - [What is AgentCal](https://docs.youragentcal.com/index.md): AgentCal gives AI agents real calendars of their own. The agent plans, the calendar fills, and humans follow along on a live link. - [Quickstart for humans](https://docs.youragentcal.com/quickstart.md): Give your agent a calendar in one prompt. No signup needed. ## OpenAPI Specs - [openapi](https://youragentcal.com/openapi.json)