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

# List your universes

> Returns every universe owned by the API key holder that has
reached `status='completed'`. Use the `id` from each entry on
every other endpoint.




## OpenAPI

````yaml /openapi.yaml get /universes
openapi: 3.1.0
info:
  title: Verseodin API
  version: 1.0.0
  description: |
    Read-only HTTP API for pulling Verseodin dashboard data:
    universes, history rows (per-day aggregates of brand visibility,
    citations, and mentions across AI search engines), and full prompt
    records including the AI's response text and cited URLs.

    The same key authorises the Verseodin Claude / MCP connector — one
    credential, two surfaces.
servers:
  - url: https://verseodin.com/api/v1
    description: Production
security:
  - BearerAuth: []
paths:
  /universes:
    get:
      tags:
        - Universes
      summary: List your universes
      description: |
        Returns every universe owned by the API key holder that has
        reached `status='completed'`. Use the `id` from each entry on
        every other endpoint.
      operationId: listUniverses
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  universes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Universe'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    Universe:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: >-
            Universe identifier. Use this in path segments on every other
            endpoint.
        universe_name:
          type: string
          description: Display name you set when creating the universe.
        website:
          type: string
          format: uri
          description: Primary domain the universe tracks.
        is_tracked:
          type: string
          description: >-
            Tracking flag — "true" means the universe re-runs on the daily
            schedule; "false" is one-shot.
        status:
          type: string
          description: Lifecycle status. The list endpoint only returns `completed` rows.
        latest_day:
          type: string
          format: date
          nullable: true
          description: >-
            Most recent day with a populated `history` row, or null if no
            history has been written yet.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
              enum:
                - authentication_error
                - permission_error
                - not_found
                - invalid_request_error
                - rate_limit_error
                - api_error
              description: Machine-readable error category.
            message:
              type: string
              description: Human-readable explanation.
  responses:
    Unauthorized:
      description: Missing / invalid / revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: >-
        Rate-limit window exceeded. Honour the `Retry-After` header before
        retrying.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: vso_<48 hex chars>
      description: |
        Generate a key at `/dashboard/settings/api-keys`. Pass it as
        `Authorization: Bearer vso_xxx` on every request.

````