> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicornfactorylisboa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List events

> Every event the team has published, past ones included, newest first. Filter on `starts_at` or `ends_at` to show only upcoming ones.



## OpenAPI

````yaml /openapi.json get /events
openapi: 3.1.0
info:
  title: Unicorn Factory Lisboa Public API
  version: 1.0.0
  description: >-
    Read-only access to our startup portfolio, founder directory, and job board
    — the same data that powers the public pages of the member portal.


    **No API key. No authentication. `GET` only. Open to every origin.**


    ## Quick start


    ```js

    const BASE = 'https://api.unicornfactorylisboa.com/v1';


    const startups = await fetch(`${BASE}/startups`).then((r) => r.json());

    const founders = await fetch(`${BASE}/founders`).then((r) => r.json());

    const jobs     = await fetch(`${BASE}/jobs`).then((r) => r.json());

    ```


    ## Fetching the whole list is the intended usage


    There is no pagination, no filtering and no fetch-one-by-id endpoint, and
    that is deliberate. The lists are small — a few hundred KB gzipped even at
    several times our current size. Fetch a directory once, hold it, and filter
    client-side. A detail page such as `/startups/acme-ai` is then a `slug`
    match against data you already have, costing no extra request.


    ## Caching and freshness


    Responses carry `Cache-Control: max-age=3600`. **An edit made in the portal
    can take up to an hour to appear here.** The `X-Cached-At` response header
    tells you when the data was last read from the database.


    Please call the API from your server or build and let your CDN or framework
    honour the cache header, rather than fetching from every visitor's browser.
    If our database is briefly unavailable we serve the last good copy rather
    than an error — a stale answer is always preferable to a broken page.


    ## Images


    `logo_url`, `avatar_url` and `image_url` point at our storage (an event's
    `image_url` may point at Luma's). You are welcome to hotlink them, but
    copying them into your own CDN at build time will be faster for your
    visitors. Tell us if you do, so we know not to break those URLs.


    ## Stability


    The `/v1` prefix is a promise: we will add fields, but we will not remove or
    rename one without shipping a `/v2`. Treat any field not documented here as
    unsupported and liable to disappear. If you need something that is not here,
    ask — whether we can publish it is usually a policy question rather than a
    technical one.
  contact:
    name: Unicorn Factory Lisboa
    url: https://unicornfactorylisboa.com/
servers:
  - url: https://api.unicornfactorylisboa.com/v1
    description: Production
  - url: https://btmkmdfnpsllqvkuknqj.supabase.co/functions/v1/public-api/v1
    description: Staging — test data only, contents are not real
security: []
tags:
  - name: Directories
    description: The public directories and programs.
paths:
  /events:
    get:
      tags:
        - Directories
      summary: List events
      description: >-
        Every event the team has published, past ones included, newest first.
        Filter on `starts_at` or `ends_at` to show only upcoming ones.
      operationId: listEvents
      responses:
        '200':
          description: The published events.
          headers:
            X-Cached-At:
              description: When this data was read from the database (ISO 8601).
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
              example:
                - id: 0b6f2d3e-8a91-4c57-b2e4-6d8f0a1c3e5b
                  name: '[Demo] Founders Breakfast'
                  description: An informal breakfast for founders in the community.
                  starts_at: '2026-12-03T09:00:00+00:00'
                  ends_at: '2026-12-03T10:30:00+00:00'
                  url: https://luma.com/example
                  image_url: https://images.lumacdn.com/example-cover.png
components:
  schemas:
    Event:
      type: object
      description: An event Unicorn Factory Lisboa runs or promotes.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type:
            - string
            - 'null'
          description: Plain text; may contain line breaks.
        starts_at:
          type: string
          format: date-time
          description: >-
            In Lisbon time with its offset, e.g. `2026-07-01T18:00:00+01:00`.
            Print the date and time as they are to show local time; parse the
            string for the exact moment.
          examples:
            - '2026-11-06T15:30:00+00:00'
        ends_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Same format as `starts_at`. `null` when no end time was given.
        url:
          type:
            - string
            - 'null'
          format: uri
          description: The event page, often on Luma, where people sign up.
        image_url:
          type:
            - string
            - 'null'
          format: uri
      required:
        - id
        - name
        - starts_at

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.