> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youragentcal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mint an agent identity and first calendar

> 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.



## OpenAPI

````yaml https://youragentcal.com/openapi.json post /v1/mint
openapi: 3.1.0
info:
  title: AgentCal API
  version: 0.5.0
  description: >-
    The AgentCal HTTP API: calendars for AI agents. Agents mint their own
    identity and credentials, create calendars, write events, share access with
    humans and other agents, and compose calendars as layers. Plain JSON over
    HTTPS; no SDK required.


    Agent-readable quickstart: https://youragentcal.com/start.md
  contact:
    url: https://youragentcal.com
servers:
  - url: https://youragentcal.com
security:
  - agentToken: []
tags:
  - name: Identity
    description: >-
      Minting and credentials. An agent mints once, keeps the token, and can
      manage extra keys.
  - name: Calendars
    description: >-
      Create calendars and manage their settings (name, slug, timezone,
      visibility, purpose, lenses).
  - name: Events
    description: One-off, recurring, and someday events on a calendar.
  - name: Grants
    description: 'Per-calendar access for other agents: owner, writer, or reader.'
  - name: Access requests
    description: Ask for access to someone else's calendar; owners approve or deny.
  - name: Share views
    description: Filtered, capability-URL projections of a calendar at /v/{slug}.
  - name: Layers
    description: Attach other calendars as layers to compose a project calendar.
paths:
  /v1/mint:
    post:
      tags:
        - Identity
      summary: Mint an agent identity and first calendar
      description: >-
        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.
      operationId: mint
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Agent name, non-empty.
                calendar:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Calendar name; defaults to the agent name.
                    timezone:
                      type: string
                      description: IANA timezone; defaults to UTC.
                      examples:
                        - America/Montreal
                onboard_token:
                  type: string
                  description: >-
                    ac_onboard_… token from a signed-in human; pre-links them as
                    owner. 30-minute validity.
            example:
              name: Claude
              calendar:
                name: Launch planning
                timezone: America/Montreal
      responses:
        '200':
          description: >-
            Minted. The token appears only in this response (idempotent replays
            included, exactly once per key).
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: ac_agent_… bearer token. Shown once.
                  agent:
                    $ref: '#/components/schemas/Agent'
                  credential:
                    $ref: '#/components/schemas/Credential'
                  calendar:
                    $ref: '#/components/schemas/Calendar'
                  claim_url:
                    type: string
                    description: >-
                      Anonymous mints only: single-use link for a human to claim
                      this agent.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Invalid onboard_token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        maxLength: 200
      description: >-
        Any unique string you generate (e.g. a UUID). Required on every mutating
        POST. Retrying with the same key and body safely replays the original
        response.
  schemas:
    Agent:
      type: object
      properties:
        id:
          type: string
          examples:
            - agt_019f4206-8288-7aef-a91a-d58290e262a0
        name:
          type: string
        created_at:
          type: string
          format: date-time
    Credential:
      type: object
      properties:
        id:
          type: string
          examples:
            - cred_…
        label:
          type: string
        scopes:
          type: array
          items:
            type: string
        expires_at:
          type: string
          format: date-time
    Calendar:
      type: object
      properties:
        id:
          type: string
          examples:
            - cal_…
        name:
          type: string
        slug:
          type: string
        timezone:
          type: string
        visibility:
          type: string
          enum:
            - unlisted
            - public
            - private
        purpose:
          type: string
        default_view:
          $ref: '#/components/schemas/Lens'
        views:
          type: array
          items:
            $ref: '#/components/schemas/Lens'
        url:
          type: string
          description: Public page at /c/{slug}.
        role:
          $ref: '#/components/schemas/Role'
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              examples:
                - invalid_request
                - unauthorized
                - insufficient_scope
                - not_found
                - slug_taken
                - last_owner
                - key_taken
            message:
              type: string
            details:
              type: object
              description: Optional extras, e.g. available slug suggestions on slug_taken.
              additionalProperties: true
    Lens:
      type: string
      enum:
        - month
        - week
        - schedule
        - timeline
    Role:
      type: string
      enum:
        - owner
        - writer
        - reader
  responses:
    BadRequest:
      description: >-
        Invalid request (invalid_json, invalid_request, invalid_event,
        missing_idempotency_key, last_owner, layer_depth…).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    agentToken:
      type: http
      scheme: bearer
      description: >-
        Agent token from POST /v1/mint (format ac_agent_…). Scopes: agent:read,
        calendar:read, calendar:write, grants:manage.

````