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

# Create a share view

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



## OpenAPI

````yaml https://youragentcal.com/openapi.json post /v1/calendars/{calendarId}/views
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}/views:
    post:
      tags:
        - Share views
      summary: Create a share view
      description: >-
        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.
      operationId: createView
      parameters:
        - $ref: '#/components/parameters/CalendarId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  maxLength: 200
                slug:
                  type: string
                  description: >-
                    Optional; immutable after creation. Omit for an unguessable
                    capability slug.
                filter:
                  $ref: '#/components/schemas/ViewFilter'
                display:
                  $ref: '#/components/schemas/ViewDisplay'
      responses:
        '200':
          description: The view, with its public url.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareView'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  parameters:
    CalendarId:
      name: calendarId
      in: path
      required: true
      schema:
        type: string
      description: cal_… public id.
    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:
    ViewFilter:
      type: object
      description: Whole-object replace on update. All keys optional.
      properties:
        layers:
          type: array
          maxItems: 20
          items:
            type: string
            maxLength: 40
          description: >-
            Layer keys to include; "main" = the calendar's own events. Defaults
            to ["main"].
        categories:
          type: array
          maxItems: 20
          items:
            type: string
            maxLength: 40
        from:
          type: string
          format: date
        to:
          type: string
          format: date
        include_someday:
          type: boolean
          default: false
        include_recurring:
          type: boolean
          default: true
    ViewDisplay:
      type: object
      properties:
        default_view:
          $ref: '#/components/schemas/Lens'
        views:
          type: array
          items:
            $ref: '#/components/schemas/Lens'
    ShareView:
      type: object
      properties:
        id:
          type: string
          examples:
            - viw_…
        name:
          type: string
        slug:
          type: string
        url:
          type: string
          description: Public page at /v/{slug}.
        filter:
          $ref: '#/components/schemas/ViewFilter'
        display:
          $ref: '#/components/schemas/ViewDisplay'
        created_at:
          type: string
          format: date-time
        revoked_at:
          type: string
          format: date-time
    Lens:
      type: string
      enum:
        - month
        - week
        - schedule
        - timeline
    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
  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.

````