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

# List items

> Returns a paginated list of items in the tenant, narrowed by the supplied query parameters. `type` matches subtypes via inheritance — `type=core.media` returns `core.media.book`, `core.media.article`, etc. `since` / `until` operate on the item's effective time (`timestamp`, falling back to `created_at`), not `updated_at`. `tier` accepts `library`, `feed`, or `all` (omitting returns both slices).

Lists are lean by default — no edges, no metadata, no extensions. The `include` parameter is the escape hatch: `?include=edges,metadata` hydrates the matching extras inline so the caller avoids the N+1 trap. See [Items — lists are lean](/concepts/items#lists-are-lean-opt-into-extras) and [Search and query](/api/search-and-query) for the filter grammar.

Cursors are stable for ~24 hours; concurrent writes don't shift pages already returned.



## OpenAPI

````yaml /openapi.json get /items
openapi: 3.1.0
info:
  title: Marfa API
  version: 4.2.0
  description: Typed data layer for structured personal data
servers: []
security: []
paths:
  /items:
    get:
      tags:
        - Items
      summary: List items
      description: >-
        Returns a paginated list of items in the tenant, narrowed by the
        supplied query parameters. `type` matches subtypes via inheritance —
        `type=core.media` returns `core.media.book`, `core.media.article`, etc.
        `since` / `until` operate on the item's effective time (`timestamp`,
        falling back to `created_at`), not `updated_at`. `tier` accepts
        `library`, `feed`, or `all` (omitting returns both slices).


        Lists are lean by default — no edges, no metadata, no extensions. The
        `include` parameter is the escape hatch: `?include=edges,metadata`
        hydrates the matching extras inline so the caller avoids the N+1 trap.
        See [Items — lists are
        lean](/concepts/items#lists-are-lean-opt-into-extras) and [Search and
        query](/api/search-and-query) for the filter grammar.


        Cursors are stable for ~24 hours; concurrent writes don't shift pages
        already returned.
      parameters:
        - schema:
            type: string
          required: false
          name: type
          in: query
        - schema:
            type: string
          required: false
          name: state
          in: query
        - schema:
            type: string
          required: false
          name: source
          in: query
        - schema:
            type: string
            enum:
              - library
              - feed
              - all
          required: false
          name: tier
          in: query
        - schema:
            type: string
          required: false
          name: tags
          in: query
        - schema:
            type: string
          required: false
          name: filter
          in: query
        - schema:
            type: string
            enum:
              - created_at
              - updated_at
              - timestamp
          required: false
          name: sort
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
          required: false
          name: direction
          in: query
        - schema:
            type: string
          required: false
          name: since
          in: query
        - schema:
            type: string
          required: false
          name: until
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
          required: false
          name: limit
          in: query
        - schema:
            type: string
          required: false
          name: cursor
          in: query
        - schema:
            type: string
          required: false
          name: include
          in: query
      responses:
        '200':
          description: Paginated list of items
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            type:
                              type: string
                            properties:
                              type: object
                              additionalProperties:
                                nullable: true
                            state:
                              type: string
                              enum:
                                - active
                                - archived
                                - trashed
                                - revoked
                            tier:
                              type: string
                              enum:
                                - library
                                - feed
                            tenant_id:
                              type: string
                              nullable: true
                            version:
                              type: number
                            schema_version:
                              type: integer
                            source:
                              type: string
                            source_id:
                              type: string
                            device:
                              type: string
                            capture_latitude:
                              type: number
                            capture_longitude:
                              type: number
                            timestamp:
                              type: string
                            created_at:
                              type: string
                            updated_at:
                              type: string
                            edges:
                              type: object
                              additionalProperties:
                                type: object
                                properties:
                                  edges:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        id:
                                          type: string
                                        tenant_id:
                                          type: string
                                          nullable: true
                                        source_id:
                                          type: string
                                        target_id:
                                          type: string
                                        edge_type:
                                          type: string
                                        properties:
                                          type: object
                                          additionalProperties:
                                            nullable: true
                                        created_at:
                                          type: string
                                        updated_at:
                                          type: string
                                      required:
                                        - id
                                        - source_id
                                        - target_id
                                        - edge_type
                                        - properties
                                        - created_at
                                        - updated_at
                                  has_more:
                                    type: boolean
                                  next_cursor:
                                    type: string
                                required:
                                  - edges
                                  - has_more
                            extensions:
                              type: object
                              additionalProperties:
                                type: object
                                additionalProperties:
                                  nullable: true
                          required:
                            - id
                            - type
                            - properties
                            - state
                            - version
                            - schema_version
                            - source
                            - timestamp
                            - created_at
                            - updated_at
                      cursor:
                        type: string
                        nullable: true
                      has_more:
                        type: boolean
                    required:
                      - data
                      - cursor
                      - has_more
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            item:
                              type: object
                              properties:
                                id:
                                  type: string
                                type:
                                  type: string
                                properties:
                                  type: object
                                  additionalProperties:
                                    nullable: true
                                state:
                                  type: string
                                  enum:
                                    - active
                                    - archived
                                    - trashed
                                    - revoked
                                tier:
                                  type: string
                                  enum:
                                    - library
                                    - feed
                                tenant_id:
                                  type: string
                                  nullable: true
                                version:
                                  type: number
                                schema_version:
                                  type: integer
                                source:
                                  type: string
                                source_id:
                                  type: string
                                device:
                                  type: string
                                capture_latitude:
                                  type: number
                                capture_longitude:
                                  type: number
                                timestamp:
                                  type: string
                                created_at:
                                  type: string
                                updated_at:
                                  type: string
                                edges:
                                  type: object
                                  additionalProperties:
                                    type: object
                                    properties:
                                      edges:
                                        type: array
                                        items:
                                          type: object
                                          properties:
                                            id:
                                              type: string
                                            tenant_id:
                                              type: string
                                              nullable: true
                                            source_id:
                                              type: string
                                            target_id:
                                              type: string
                                            edge_type:
                                              type: string
                                            properties:
                                              type: object
                                              additionalProperties:
                                                nullable: true
                                            created_at:
                                              type: string
                                            updated_at:
                                              type: string
                                          required:
                                            - id
                                            - source_id
                                            - target_id
                                            - edge_type
                                            - properties
                                            - created_at
                                            - updated_at
                                      has_more:
                                        type: boolean
                                      next_cursor:
                                        type: string
                                    required:
                                      - edges
                                      - has_more
                                extensions:
                                  type: object
                                  additionalProperties:
                                    type: object
                                    additionalProperties:
                                      nullable: true
                              required:
                                - id
                                - type
                                - properties
                                - state
                                - version
                                - schema_version
                                - source
                                - timestamp
                                - created_at
                                - updated_at
                            metadata:
                              type: object
                              properties:
                                item_id:
                                  type: string
                                tags:
                                  type: array
                                  items:
                                    type: string
                                extensions:
                                  type: object
                                  additionalProperties:
                                    nullable: true
                              required:
                                - item_id
                                - tags
                                - extensions
                          required:
                            - item
                            - metadata
                      cursor:
                        type: string
                        nullable: true
                      has_more:
                        type: boolean
                    required:
                      - data
                      - cursor
                      - has_more
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - validation_error
                          - missing_required_field
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties:
                          nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - unauthorized
                      message:
                        type: string
                      details:
                        type: object
                        additionalProperties:
                          nullable: true
                    required:
                      - code
                      - message
                required:
                  - error
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key or OAuth Token
      description: Pass an API key (marfa_k1_...) or OAuth access token (marfa_at_...)

````