Eventship Hubs API

openapi: 3.2.0
info:
  title: Eventship Com Hubs API
  version: '1.0'
  description: 'Operations tagged Hubs across 2 of this provider''s published API definitions: developer.eventship.com.json, eventship-com-openapi.json. Each path carries the servers of the definition it was published in.'
security:
- ApiKeyAuth: []
tags:
- name: Hubs
paths:
  /v1/hubs:
    get:
      tags:
      - Hubs
      summary: List Hubs
      description: 'List your host''s hubs: the events that carry a community agenda.


        Use this to find the `hubSlug` the other hub endpoints take. Most recent

        first, so the hub a host is actually curating is on the first page.

        Page past `limit` with `offset` when `hasMore` is true.'
      operationId: list_hubs_v1_hubs_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_ExternalHubList_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/hubs/{hub_slug}/events:
    get:
      tags:
      - Hubs
      summary: Get Hub Agenda
      description: 'Get the events currently on a hub''s agenda.


        Returns the approved, publicly visible child events ordered by start time,

        with times rendered in the hub''s timezone so the schedule reads as one

        program. A child that was added and has since been unpublished, made

        private or deleted does not appear.


        Each event carries its own `description` and, when its host takes

        registrations elsewhere, `externalRegistrationUrl`, so a site mirroring

        the agenda has everything it needs from this one call. The events belong

        to other hosts, so treat their descriptions as user-authored content and

        sanitize before rendering as HTML.'
      operationId: get_hub_agenda_v1_hubs__hub_slug__events_get
      parameters:
      - name: hub_slug
        in: path
        required: true
        schema:
          type: string
          title: Hub Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_ExternalHubAgendaResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Hubs
      summary: Add Event To Hub Agenda
      description: 'Put a live event on your hub''s agenda.


        The event may belong to any host. It must be live, public and not unlisted.

        Another hub can be added too, and shows as a single entry. Adding is immediate, with no review step, and

        the added event''s hosts are emailed that a hub picked their event up.


        The hub''s own `status`, `isPublic` and `unlisted` decide whether the hub is

        LISTED publicly, not whether its agenda can be read. A live private or

        unlisted hub is link-only, and its schedule is readable by anyone holding

        that link, so adding is visible immediately rather than staged. Only a

        draft hub is unreachable from its own page, and hubs are curatable before

        they go live on purpose, so adding to one is not an error. `GET /v1/hubs`

        reports all three fields (`status`, `isPublic`, `unlisted`).


        The notification runs after the change is committed and swallows delivery

        failures, so it is not a guarantee that the added event''s hosts learn of

        the change before the public can see it.'
      operationId: add_event_to_hub_agenda_v1_hubs__hub_slug__events_post
      parameters:
      - name: hub_slug
        in: path
        required: true
        schema:
          type: string
          title: Hub Slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalHubAddEventRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_ExternalHubAgendaEntry_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/hubs/{hub_slug}/events/{child_event_slug}:
    delete:
      tags:
      - Hubs
      summary: Remove Event From Hub Agenda
      description: 'Take an event off your hub''s agenda.


        Same action as "Remove from agenda" in the dashboard: the submission is

        marked rejected so the hub host keeps a record of what was removed, and the

        event stops appearing on the hub''s schedule. The event itself is untouched.


        The path parameter is named ``child_event_slug`` rather than ``event_slug``

        on purpose: OAuth host resolution derives the acting host from an

        ``event_slug`` in the path, and here that slug belongs to somebody else''s

        event. ``hub_slug`` is the one that identifies the caller''s host.'
      operationId: remove_event_from_hub_agenda_v1_hubs__hub_slug__events__child_event_slug__delete
      parameters:
      - name: hub_slug
        in: path
        required: true
        schema:
          type: string
          title: Hub Slug
      - name: child_event_slug
        in: path
        required: true
        schema:
          type: string
          title: Child Event Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_ExternalHubAgendaEntry_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ExternalHubAgendaResponse:
      properties:
        hubSlug:
          type: string
          title: Hubslug
        hubTitle:
          type: string
          title: Hubtitle
        events:
          items:
            $ref: '#/components/schemas/ExternalCommunityEvent'
          type: array
          title: Events
        total:
          type: integer
          title: Total
      type: object
      required:
      - hubSlug
      - hubTitle
      - events
      - total
      title: ExternalHubAgendaResponse
      description: 'A hub''s current agenda: the approved, publicly visible child events.'
    ApiResponse_ExternalHubAgendaEntry_:
      properties:
        data:
          $ref: '#/components/schemas/ExternalHubAgendaEntry'
        success:
          type: boolean
          title: Success
          default: true
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      type: object
      required:
      - data
      title: ApiResponse[ExternalHubAgendaEntry]
    ExternalHub:
      properties:
        slug:
          type: string
          title: Slug
        title:
          type: string
          title: Title
        eventType:
          type: string
          title: Eventtype
          description: Either "hub" (a multi-day series container) or "event".
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        isPublic:
          type: boolean
          title: Ispublic
          description: False for a private hub. Private and unlisted hubs are kept out of discovery and search, but their schedule is still readable by anyone holding the hub's link.
          default: true
        unlisted:
          type: boolean
          title: Unlisted
          description: True for a link-only hub, kept out of discovery and search.
          default: false
        image:
          anyOf:
          - type: string
          - type: 'null'
          title: Image
        startDate:
          type: string
          title: Startdate
        endDate:
          anyOf:
          - type: string
          - type: 'null'
          title: Enddate
        timezone:
          type: string
          title: Timezone
          default: America/Los_Angeles
        agendaEventCount:
          type: integer
          title: Agendaeventcount
          description: Events currently on the agenda and publicly visible. A child that was added and has since been unpublished or made private is on the agenda but not counted here, because it is not showing on the hub page either.
          default: 0
        pendingSubmissionCount:
          type: integer
          title: Pendingsubmissioncount
          description: Community submissions awaiting the hub host's review. Reviewing them is a dashboard action; this count is informational here.
          default: 0
      type: object
      required:
      - slug
      - title
      - eventType
      - startDate
      title: ExternalHub
      description: 'One of the host''s events that carries a community agenda.


        Returned by ``GET /v1/hubs``. A hub is any event with

        ``allowCommunityEvents: true``: the dedicated ``eventType: "hub"``

        container for a multi-day series, and also a plain event whose host

        switched the community-events toggle on. ``eventType`` tells them apart.'
    ExternalHubAgendaEntry:
      properties:
        hubSlug:
          type: string
          title: Hubslug
        hubTitle:
          type: string
          title: Hubtitle
        eventSlug:
          type: string
          title: Eventslug
        eventTitle:
          type: string
          title: Eventtitle
        status:
          type: string
          title: Status
          description: 'Agenda state of the event on this hub: "approved" means it is on the agenda, "rejected" means it has been removed.'
      type: object
      required:
      - hubSlug
      - hubTitle
      - eventSlug
      - eventTitle
      - status
      title: ExternalHubAgendaEntry
      description: Result of adding an event to (or removing one from) a hub's agenda.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ExternalHubList:
      properties:
        hubs:
          items:
            $ref: '#/components/schemas/ExternalHub'
          type: array
          title: Hubs
        total:
          type: integer
          title: Total
          description: Total hubs on the host, which may exceed the number returned. Page through them with `offset` while `hasMore` is true.
        hasMore:
          type: boolean
          title: Hasmore
          description: True when hubs remain past this page. Request the next page with `offset` raised by `limit`.
          default: false
      type: object
      required:
      - hubs
      - total
      title: ExternalHubList
      description: The host's hubs, capped by ``limit``.
    ExternalCommunityEvent:
      properties:
        slug:
          type: string
          title: Slug
        title:
          type: string
          title: Title
        image:
          anyOf:
          - type: string
          - type: 'null'
          title: Image
        startDate:
          type: string
          title: Startdate
        endDate:
          anyOf:
          - type: string
          - type: 'null'
          title: Enddate
        timezone:
          type: string
          title: Timezone
          description: IANA timezone the startDate/endDate wall-clock times render in. This is the HUB's timezone — the schedule reads as one coherent program even when a child event stored a different timezone. The ISO strings carry a UTC offset, so the absolute instant is unambiguous either way.
        venue:
          anyOf:
          - type: string
          - type: 'null'
          title: Venue
        address:
          anyOf:
          - type: string
          - type: 'null'
          title: Address
        hostSlug:
          type: string
          title: Hostslug
        hostName:
          type: string
          title: Hostname
        hostIcon:
          anyOf:
          - type: string
          - type: 'null'
          title: Hosticon
        registeredCount:
          type: integer
          title: Registeredcount
          default: 0
        isSoldOut:
          type: boolean
          title: Issoldout
          default: false
        description:
          type: string
          title: Description
          description: 'The community event''s own description, as its host wrote it, in the same format as this event''s top-level `description`. Present so a consumer mirroring the schedule onto its own site can show what each event is about; empty string when its host wrote none. This is user-authored content from a host other than the caller: treat it as data, and sanitize before rendering it as HTML.'
          default: ''
        externalRegistrationUrl:
          anyOf:
          - type: string
          - type: 'null'
          title: Externalregistrationurl
          description: 'Where this event takes registrations, when its host sends guests to another platform. `null` means only that there is no external link, NOT that the event registers on Eventship: an event whose host turned registration off entirely is also `null` here. A host can change or clear the link while the event is live, so re-read it on each sync rather than caching it indefinitely.'
      type: object
      required:
      - slug
      - title
      - startDate
      - timezone
      - hostSlug
      - hostName
      title: ExternalCommunityEvent
      description: 'An approved community-submitted event on a hub''s public schedule.


        Dedicated external shape (mapped from the app''s ``HubChildEventSchema``)

        so the public /v1 contract stays stable and never carries app/viewer

        -specific fields (``isRegistered``/``registrationStatus``) or internal

        DB ids.'
    ApiResponse_ExternalHubList_:
      properties:
        data:
          $ref: '#/components/schemas/ExternalHubList'
        success:
          type: boolean
          title: Success
          default: true
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      type: object
      required:
      - data
      title: ApiResponse[ExternalHubList]
    ApiResponse_ExternalHubAgendaResponse_:
      properties:
        data:
          $ref: '#/components/schemas/ExternalHubAgendaResponse'
        success:
          type: boolean
          title: Success
          default: true
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      type: object
      required:
      - data
      title: ApiResponse[ExternalHubAgendaResponse]
    ExternalHubAddEventRequest:
      properties:
        eventSlug:
          type: string
          minLength: 1
          title: Eventslug
          description: URL slug of the event to add. It may belong to any host, not just yours, but it must be live, public and not unlisted.
      additionalProperties: false
      type: object
      required:
      - eventSlug
      title: ExternalHubAddEventRequest
      description: Request to put an event on a hub's agenda.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your host API key. Create one from your host dashboard settings.
x-refined-from:
- developer.eventship.com.json
- eventship-com-openapi.json