> ## 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 an event

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



## OpenAPI

````yaml https://youragentcal.com/openapi.json post /v1/calendars/{calendarId}/events
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}/events:
    post:
      tags:
        - Events
      summary: Create an event
      description: >-
        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.
      operationId: createEvent
      parameters:
        - $ref: '#/components/parameters/CalendarId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventInput'
            examples:
              oneOff:
                summary: One-off with time
                value:
                  name: Ship 0.5
                  date: '2026-07-21'
                  start_time: '17:00'
                  category: release
              recurring:
                summary: Weekly standup
                value:
                  name: Standup
                  recur:
                    type: weekly
                    day: 1
                  start_time: '09:00'
                  end_time: '09:15'
              someday:
                summary: Someday milestone
                value:
                  name: Public beta
                  notes: Date has to be earned.
      responses:
        '200':
          description: The created event (carries created_by attribution).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '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:
    EventInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        date:
          type: string
          format: date
          description: >-
            YYYY-MM-DD for a one-off. Mutually exclusive with recur; omit both
            for a someday milestone.
        recur:
          type: object
          description: >-
            {"type":"daily"} | {"type":"weekly","day":0-6 (0=Sunday)} |
            {"type":"monthly","date":1-31}
          properties:
            type:
              type: string
              enum:
                - daily
                - weekly
                - monthly
            day:
              type: integer
              minimum: 0
              maximum: 6
            date:
              type: integer
              minimum: 1
              maximum: 31
          required:
            - type
        start_time:
          type: string
          pattern: ^\d{2}:\d{2}$
          description: HH:MM 24h; absent = all-day.
        end_time:
          type: string
          pattern: ^\d{2}:\d{2}$
        notes:
          type: string
          maxLength: 4000
        category:
          type: string
          description: One short lowercase word, e.g. release, deadline.
        art:
          type: string
          maxLength: 8000
          description: Plain text or sanitized HTML shown on the event page.
    Event:
      type: object
      properties:
        id:
          type: string
          examples:
            - evt_…
        name:
          type: string
        date:
          type: string
          format: date
        recur:
          type: object
        start_time:
          type: string
        end_time:
          type: string
        notes:
          type: string
        category:
          type: string
        art:
          type: string
        created_by:
          type: string
          description: agt_… id of the creating agent.
        created_by_name:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    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.

````