Crafting Event Finder Organizers API

openapi: 3.2.0
info:
  title: Crafting Event Finder Organizers API
  version: 1.0.0
  description: Everything the site does is available here, and as MCP tools at /api/mcp.
servers:
- url: https://craftingeventfinder.com
tags:
- name: organizers
paths:
  /api/invites/{token}:
    get:
      summary: Look up an organizer invite by its link token
      description: The invite's still-published events to claim, and whether the link is open ("ok"), already used, expired or unknown. Never reveals the invited address.
      tags:
      - organizers
      security: []
      parameters:
      - schema:
          type: string
        required: true
        name: token
        in: path
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitePage'
        '503':
          description: 503 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      operationId: getApiInvitesByToken
      x-operation-id-source: derived
  /api/invites/{token}/claim:
    post:
      summary: Claim events through an invite link
      description: 'Signed in with any email - the link itself is the proof, so a forwarded invite works too. Claims a non-empty subset of the invite''s own events: an unowned one becomes the caller''s; one someone else owns, or one an admin removed them from, waits as a pending claim for an admin; granting anything promotes the caller to organizer and may grant the early-organizer featured perk. 410 once the link has already been used or has expired.'
      tags:
      - organizers
      security:
      - cookieAuth: []
      - bearerAuth: []
      parameters:
      - schema:
          type: string
        required: true
        name: token
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                eventIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  minItems: 1
                  maxItems: 20
              required:
              - eventIds
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteClaimResult'
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: 401 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: 403 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '410':
          description: 410 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      operationId: postApiInvitesByTokenClaim
      x-operation-id-source: derived
  /api/organizers/{slug}:
    get:
      summary: Get an organizer's public page
      description: 'An organizer''s public profile (name, About, website, town and state, crafts and picture) with their published events on this site: upcoming soonest first (at most 50), then the newest 12 past. Only organizers with a display name have a public page; anyone else is 404.'
      tags:
      - organizers
      security: []
      parameters:
      - schema:
          type: string
        required: true
        name: slug
        in: path
      responses:
        '200':
          description: 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicOrganizer'
        '404':
          description: 404 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: 503 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      operationId: getApiOrganizersBySlug
      x-operation-id-source: derived
components:
  schemas:
    InvitePage:
      type: object
      properties:
        status:
          type: string
          enum:
          - ok
          - used
          - expired
          - unknown
        events:
          type: array
          items:
            $ref: '#/components/schemas/InviteEvent'
      required:
      - status
      - events
    PublicOrganizer:
      type: object
      properties:
        slug:
          type: string
          description: 'The public address''s last part: /organizers/{slug}'
        displayName:
          type: string
        about:
          type:
          - string
          - 'null'
        website:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        crafts:
          type: array
          items:
            type: string
          description: Top-level craft slugs, in taxonomy order
        avatarUrl:
          type:
          - string
          - 'null'
          description: The 512px picture, or null when the default badge shows
        avatarSmallUrl:
          type:
          - string
          - 'null'
          description: The 96px picture
        defaultAvatar:
          type: string
          description: The built-in badge, '<craft icon>-<color 1-6>'
        upcoming:
          type: array
          items:
            $ref: '#/components/schemas/OrganizerEvent'
          description: Published events still to come on this site, soonest first, at most 50
        past:
          type: array
          items:
            $ref: '#/components/schemas/OrganizerEvent'
          description: The newest 12 published events that are over
      required:
      - slug
      - displayName
      - about
      - website
      - city
      - state
      - crafts
      - avatarUrl
      - avatarSmallUrl
      - defaultAvatar
      - upcoming
      - past
    PublicEventImage:
      type: object
      properties:
        url:
          type: string
          description: The picture at most 1600px wide (WebP)
        cardUrl:
          type: string
          description: The picture at most 600px wide (WebP), for cards
        alt:
          type: string
          description: The description read to people who can't see the picture
        width:
          type: integer
        height:
          type: integer
        focusX:
          type: number
          description: The focus point across, 0 (left) to 1 (right), kept in view when the picture is cropped
        focusY:
          type: number
          description: The focus point down, 0 (top) to 1 (bottom)
      required:
      - url
      - cardUrl
      - alt
      - width
      - height
      - focusX
      - focusY
    OrganizerEvent:
      allOf:
      - $ref: '#/components/schemas/Event'
      - type: object
        properties:
          nextStartDate:
            type:
            - string
            - 'null'
            description: The next occurrence's start date, or null when it has none left (a repeating event's own dates are only its first)
          nextEndDate:
            type:
            - string
            - 'null'
        required:
        - nextStartDate
        - nextEndDate
    InviteEvent:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        title:
          type: string
        dateLabel:
          type: string
        place:
          type: string
        url:
          type: string
      required:
      - id
      - slug
      - title
      - dateLabel
      - place
      - url
    Event:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        title:
          type: string
        description:
          type:
          - string
          - 'null'
        summary:
          type:
          - string
          - 'null'
        start_date:
          type: string
        end_date:
          type:
          - string
          - 'null'
        start_time:
          type:
          - string
          - 'null'
        end_time:
          type:
          - string
          - 'null'
        timezone:
          type:
          - string
          - 'null'
        city:
          type: string
        state:
          type: string
        venue:
          type:
          - string
          - 'null'
        location_kind:
          type: string
          enum:
          - venue
          - online
          - hybrid
          - multi
          description: venue, online, hybrid (one place and online at once) or multi (several places)
        street_address:
          type:
          - string
          - 'null'
        postal_code:
          type:
          - string
          - 'null'
        signup_note:
          type:
          - string
          - 'null'
        craft_types:
          type: array
          items:
            type: string
        event_type:
          type:
          - string
          - 'null'
        tags:
          type: array
          items:
            type: string
        url:
          type:
          - string
          - 'null'
        source_url:
          type:
          - string
          - 'null'
        organizer_name:
          type:
          - string
          - 'null'
        lat:
          type:
          - number
          - 'null'
        lng:
          type:
          - number
          - 'null'
        price_note:
          type:
          - string
          - 'null'
        is_free:
          type:
          - boolean
          - 'null'
        published_at:
          type:
          - string
          - 'null'
        languages:
          type: array
          items:
            type: string
          description: The languages it is held in, as BCP 47 codes (en, es); empty when unknown
        hosted_by:
          type:
          - string
          - 'null'
          description: The group or shop hosting an online or hybrid event, when given
        hasJoinDetails:
          type: boolean
          description: An online or hybrid event with join details (link, meeting ID, passcode or dial-in); get them from GET /api/events/{slug}/join
        joinPlatform:
          type:
          - string
          - 'null'
          enum:
          - zoom
          - meet
          - teams
          - webex
          - facebook
          - youtube
          - other
          - null
          description: The online meeting platform, for online events
        contactName:
          type:
          - string
          - 'null'
          description: The organizer's contact person
        hasContactDetails:
          type: boolean
          description: A contact email or phone exists; get them from GET /api/events/{slug}/contact
        isNew:
          type: boolean
          description: Published within the last 7 days
        updatedRecently:
          type: boolean
          description: Its date, time, place or price changed within the last 7 days
        changedFields:
          type: array
          items:
            type: string
            enum:
            - date
            - time
            - place
            - price
          description: What changed (date, time, place, price); empty unless updatedRecently
        contentChangedAt:
          type:
          - string
          - 'null'
          description: When its date, time, place or price last changed; null if never
        cancelled:
          type: boolean
          description: A cancelled event (only GET /api/events/{slug} returns one, until its dates pass); lists never include it
        scheduleChange:
          type:
          - string
          - 'null'
          enum:
          - postponed
          - rescheduled
          - moved_online
          - null
          description: postponed (new date to come), rescheduled or moved_online; null when it runs as listed
        previousStartDate:
          type:
          - string
          - 'null'
          description: The start date a rescheduled event had before (YYYY-MM-DD); null otherwise
        images:
          type: array
          items:
            $ref: '#/components/schemas/PublicEventImage'
          description: The organizer's pictures in order, at most 6; the first is the cover. Empty when there are none
      required:
      - id
      - slug
      - title
      - description
      - summary
      - start_date
      - end_date
      - start_time
      - end_time
      - timezone
      - city
      - state
      - venue
      - location_kind
      - street_address
      - postal_code
      - signup_note
      - craft_types
      - event_type
      - tags
      - url
      - source_url
      - organizer_name
      - lat
      - lng
      - price_note
      - is_free
      - published_at
      - languages
      - hosted_by
      - hasJoinDetails
      - joinPlatform
      - contactName
      - hasContactDetails
      - isNew
      - updatedRecently
      - changedFields
      - contentChangedAt
      - cancelled
      - scheduleChange
      - previousStartDate
      - images
    ApiError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details: {}
          required:
          - code
          - message
      required:
      - error
    InviteClaimResult:
      type: object
      properties:
        granted:
          type: array
          items:
            $ref: '#/components/schemas/InviteEvent'
        pending:
          type: array
          items:
            $ref: '#/components/schemas/InviteEvent'
        skipped:
          type: array
          items:
            $ref: '#/components/schemas/InviteEvent'
        perk:
          type:
          - object
          - 'null'
          properties:
            eventId:
              type: string
            endsOn:
              type: string
          required:
          - eventId
          - endsOn
      required:
      - granted
      - pending
      - skipped
      - perk
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key from /admin/api-keys: Authorization: Bearer cef_<scope>_...'
    cookieAuth:
      type: apiKey
      in: cookie
      name: cef_session