swagger: '2.0'
info:
  title: Limitless Developer Chats API
  description: 'API for accessing lifelogs, providing transparency and portability to user data.


    ## Rate Limiting

    The API implements rate limiting to ensure fair usage and protect against abuse.

    - **Default Rate Limit:** 180 requests per minute per API key

    - **Rate Limit Response:** When exceeded, returns 429 Too Many Requests with retry information

    '
  version: 1.0.0
host: api.limitless.ai
basePath: /
schemes:
- https
tags:
- name: Chats
paths:
  /v1/chats:
    get:
      operationId: getChats
      summary: Returns a list of chats.
      description: Returns a list of chats (ask-ai conversations) for the authenticated user. Pagination is supported.
      parameters:
      - in: query
        name: cursor
        type: string
        description: Cursor for pagination to retrieve the next set of chats.
      - in: query
        name: direction
        type: string
        enum:
        - asc
        - desc
        default: desc
        description: Sort direction for chats.
      - in: query
        name: limit
        type: integer
        description: Maximum number of chats to return. Upper limit is 100.
      - in: query
        name: timezone
        type: string
        description: IANA timezone specifier. If missing, UTC is used.
      - in: query
        name: isScheduled
        type: boolean
        description: When true, only return chats generated by scheduled prompts; when false, only non-scheduled chats.
      - in: query
        name: globalPromptId
        type: string
        description: Filter to chats generated by scheduled prompts that match the given globalPromptId (see curated prompts).
      responses:
        '200':
          description: Successful response with chats.
          schema:
            $ref: '#/definitions/ChatsResponse'
        '401':
          description: Unauthorized - Invalid or missing API key.
        '429':
          description: Too Many Requests - Rate limit exceeded.
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message indicating rate limit exceeded.
              retryAfter:
                type: string
                description: Number of seconds to wait before retrying.
      tags:
      - Chats
  /v1/chats/{id}:
    get:
      operationId: getChat
      summary: Returns a single chat by ID.
      description: Returns a specific chat (ask-ai conversation) by its unique identifier. Users can only access their own chats or public chats.
      parameters:
      - in: path
        name: id
        type: string
        required: true
        description: Unique identifier of the chat to retrieve.
      - in: query
        name: timezone
        type: string
        description: IANA timezone specifier. If missing, UTC is used.
      responses:
        '200':
          description: Successful response with a single chat.
          schema:
            $ref: '#/definitions/ChatResponse'
        '404':
          description: Chat not found.
        '401':
          description: Unauthorized - Invalid or missing API key.
        '429':
          description: Too Many Requests - Rate limit exceeded.
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message indicating rate limit exceeded.
              retryAfter:
                type: string
                description: Number of seconds to wait before retrying.
      tags:
      - Chats
    delete:
      operationId: deleteChat
      summary: Deletes a single chat by ID.
      description: Permanently deletes a specific chat (ask-ai conversation) by its unique identifier. Users can only delete their own chats.
      parameters:
      - in: path
        name: id
        type: string
        required: true
        description: Unique identifier of the chat to delete.
      responses:
        '200':
          description: Chat successfully deleted.
          schema:
            $ref: '#/definitions/DeleteChatResponse'
        '404':
          description: Chat not found.
        '401':
          description: Unauthorized - Invalid or missing API key.
      tags:
      - Chats
definitions:
  ChatResponse:
    type: object
    properties:
      data:
        $ref: '#/definitions/ChatResponseData'
  Chat:
    type: object
    properties:
      id:
        type: string
        description: Unique identifier for the chat.
      summary:
        type: string
        description: Brief summary of the chat conversation.
        x-nullable: true
      createdAt:
        type: string
        format: date-time
        description: Timestamp when the chat was created (ISO 8601 string).
      startedAt:
        type: string
        format: date-time
        description: Timestamp of the first message in the chat (ISO 8601 string).
      messages:
        type: array
        items:
          $ref: '#/definitions/ChatMessage'
        description: List of messages in the chat.
      visibility:
        type: string
        enum:
        - private
        - public
        - internal
        description: Visibility setting for the chat.
  ToolCall:
    type: object
    properties:
      id:
        type: string
        description: Unique identifier for the tool call.
      toolName:
        type: string
        description: Name of the tool that was called.
      args:
        type: object
        description: Arguments passed to the tool.
        x-nullable: true
  ChatResponseData:
    type: object
    properties:
      chat:
        $ref: '#/definitions/Chat'
        x-nullable: true
  MetaChats:
    type: object
    properties:
      nextCursor:
        type: string
        description: Cursor for pagination to retrieve the next set of chats, bound to the query parameters from the original request.
        x-nullable: true
      count:
        type: integer
        description: Number of chats in the current response.
  DeleteChatResponse:
    type: object
    properties:
      data:
        type: object
        properties:
          success:
            type: boolean
            description: Indicates whether the deletion was successful.
  ChatsResponse:
    type: object
    properties:
      data:
        $ref: '#/definitions/ChatsResponseData'
      meta:
        type: object
        properties:
          chats:
            $ref: '#/definitions/MetaChats'
  ChatMessage:
    type: object
    properties:
      id:
        type: string
        description: Unique identifier for the message.
      text:
        type: string
        description: Text content of the message.
        x-nullable: true
      toolCalls:
        type: array
        items:
          $ref: '#/definitions/ToolCall'
        description: Tool calls made in this message.
        x-nullable: true
      toolResults:
        type: array
        items:
          $ref: '#/definitions/ToolResult'
        description: Results from tool calls in this message.
        x-nullable: true
      createdAt:
        type: string
        format: date-time
        description: Timestamp when the message was created (ISO 8601 string).
      user:
        type: object
        properties:
          role:
            type: string
            enum:
            - user
            - assistant
            - system
            - tool
            description: Role of the sender for this message.
          name:
            type: string
            description: Name of the user.
            x-nullable: true
  ToolResult:
    type: object
    properties:
      result:
        type: object
        description: Result returned by the tool.
      isError:
        type: boolean
        description: Whether the tool call resulted in an error.
      toolCallId:
        type: string
        description: ID of the tool call this result corresponds to.
      toolName:
        type: string
        description: Name of the tool that was called.
      entriesReturned:
        type: array
        items:
          type: object
          properties:
            title:
              type: string
              description: Title of the entry returned by the tool.
            id:
              type: string
              description: ID of the entry returned by the tool.
        description: Limited information about entries returned by the tool.
        x-nullable: true
  ChatsResponseData:
    type: object
    properties:
      chats:
        type: array
        items:
          $ref: '#/definitions/Chat'