> ## Documentation Index > Fetch the complete documentation index at: https://docs.refmatter.com/llms.txt > Use this file to discover all available pages before exploring further. # List workspace references using opaque keyset pagination ## OpenAPI ````yaml /api-reference/openapi.json get /v1/references openapi: 3.1.0 info: title: Refmatter API version: 0.1.0 description: >- Reference memory for AI creative agents. Every operation carries x-implementation-status; only implemented operations are availability claims. servers: - url: https://api.refmatter.com security: - bearerApiKey: [] - sessionCookie: [] tags: - name: auth - name: workspaces - name: ingestions - name: references - name: media - name: sourceRoutes paths: /v1/references: get: tags: - references summary: List workspace references using opaque keyset pagination operationId: referencesList parameters: - name: cursor in: query required: false description: Opaque keyset cursor from a previous page schema: type: string - name: limit in: query required: false description: Page size, 1..100, default 30 schema: type: integer minimum: 1 maximum: 100 - name: state in: query required: false description: Filter by reference state schema: enum: - processing - ready - failed - name: platform in: query required: false description: Filter by source platform schema: enum: - youtube - tiktok - name: mediaKind in: query required: false description: Filter by primary media kind schema: enum: - video - audio - image - poster - name: createdAfter in: query required: false description: Inclusive lower creation bound (RFC 3339 UTC) schema: type: string format: date-time - name: createdBefore in: query required: false description: Exclusive upper creation bound (RFC 3339 UTC) schema: type: string format: date-time responses: '200': description: One deterministic reference page content: application/json: schema: $ref: '#/components/schemas/ReferenceList' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Action not permitted content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: Revision or idempotency conflict content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Request cannot be fulfilled by the current source contract content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '503': description: Route or dependency unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - bearerApiKey: [] - sessionCookie: [] components: schemas: ReferenceList: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: items: type: array items: type: object properties: id: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ workspaceId: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ canonicalContentId: anyOf: - type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ - type: 'null' sourceIngestionId: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ platform: type: string enum: - youtube - tiktok canonicalUrl: anyOf: - type: string minLength: 1 maxLength: 2048 - type: 'null' state: type: string enum: - processing - ready - failed mediaAvailability: type: string enum: - processing - ready - expired - failed - unavailable failureCode: anyOf: - type: string enum: - invalid_input - unauthenticated - invalid_credential - credential_conflict - forbidden - policy_blocked - route_disabled - route_degraded - not_found - bootstrap_conflict - last_owner_conflict - revision_conflict - idempotency_conflict - unavailable_private - unavailable_restricted - unavailable_removed - unsupported_object - unsupported_media - limit_exceeded - rate_limited - source_changed - network_timeout - network_transport - media_invalid - storage_unavailable - retry_exhausted - internal_error - type: 'null' retryable: type: - boolean - 'null' createdAt: type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-([0-2]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$ updatedAt: type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-([0-2]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$ revision: type: integer minimum: 0 maximum: 9007199254740991 sourceObserved: anyOf: - type: object properties: observationId: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ observedAt: type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-([0-2]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$ sourceTitle: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' sourceDescription: anyOf: - type: string minLength: 0 maxLength: 10000 - type: 'null' channelId: anyOf: - type: string minLength: 0 maxLength: 160 - type: 'null' channelName: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' publishedAt: anyOf: - type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-([0-2]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$ - type: 'null' durationMs: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' viewCount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' likeCount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' required: - observationId - observedAt - sourceTitle - sourceDescription - channelId - channelName - publishedAt - durationMs - viewCount - likeCount additionalProperties: false - type: 'null' humanAuthored: type: object properties: customTitle: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' notes: type: string minLength: 0 maxLength: 20000 tags: maxItems: 50 type: array items: type: string minLength: 1 maxLength: 64 required: - customTitle - notes - tags additionalProperties: false primaryMediaId: anyOf: - type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ - type: 'null' posterMediaId: anyOf: - type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ - type: 'null' required: - id - workspaceId - canonicalContentId - sourceIngestionId - platform - canonicalUrl - state - mediaAvailability - failureCode - retryable - createdAt - updatedAt - revision - sourceObserved - humanAuthored - primaryMediaId - posterMediaId additionalProperties: false nextCursor: anyOf: - type: string minLength: 16 maxLength: 2048 pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$ - type: 'null' required: - items - nextCursor additionalProperties: false ErrorEnvelope: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: error: type: object properties: code: type: string enum: - invalid_input - unauthenticated - invalid_credential - credential_conflict - forbidden - policy_blocked - route_disabled - route_degraded - not_found - bootstrap_conflict - last_owner_conflict - revision_conflict - idempotency_conflict - unavailable_private - unavailable_restricted - unavailable_removed - unsupported_object - unsupported_media - limit_exceeded - rate_limited - source_changed - network_timeout - network_transport - media_invalid - storage_unavailable - retry_exhausted - internal_error message: type: string minLength: 1 maxLength: 240 retryable: type: boolean requestId: type: string minLength: 8 maxLength: 128 pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$ details: type: object propertyNames: type: string additionalProperties: type: - string - number - boolean required: - code - message - retryable - requestId - details additionalProperties: false required: - error additionalProperties: false securitySchemes: bearerApiKey: type: http scheme: bearer sessionCookie: type: apiKey in: cookie name: social_session ````