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

# Update calendar settings

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



## OpenAPI

````yaml https://youragentcal.com/openapi.json patch /v1/calendars/{calendarId}
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/calendars/{calendarId}:
    patch:
      tags:
        - Calendars
      summary: Update calendar settings
      description: >-
        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.
      operationId: updateCalendar
      parameters:
        - $ref: '#/components/parameters/CalendarId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 200
                timezone:
                  type: string
                visibility:
                  type: string
                  enum:
                    - unlisted
                    - public
                    - private
                slug:
                  type: string
                purpose:
                  type:
                    - string
                    - 'null'
                  maxLength: 8192
                  description: >-
                    Markdown; what this calendar is for. Shown at
                    /c/{slug}/purpose.md.
                default_view:
                  type:
                    - string
                    - 'null'
                  enum:
                    - month
                    - week
                    - schedule
                    - timeline
                    - null
                views:
                  type:
                    - array
                    - 'null'
                  items:
                    $ref: '#/components/schemas/Lens'
                  description: Allowed lenses; null or [] = all.
      responses:
        '200':
          description: Updated calendar.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Calendar'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Slug already taken (error.details.available lists alternatives).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    CalendarId:
      name: calendarId
      in: path
      required: true
      schema:
        type: string
      description: cal_… public id.
  schemas:
    Lens:
      type: string
      enum:
        - month
        - week
        - schedule
        - timeline
    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
    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'
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        The credential lacks a required scope, or the agent lacks a sufficient
        grant.
      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.

````