> ## 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. # Read a workspace reference ## OpenAPI ````yaml /api-reference/openapi.json get /v1/references/{referenceId} 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/{referenceId}: get: tags: - references summary: Read a workspace reference operationId: referencesGet parameters: - name: referenceId in: path required: true description: Opaque reference identifier schema: type: string format: uuid responses: '200': description: Reference detail content: application/json: schema: $ref: '#/components/schemas/ReferenceDetail' '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: ReferenceDetail: $schema: https://json-schema.org/draft/2020-12/schema 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' machineDerived: anyOf: - type: object properties: mediaKind: type: string enum: - video - audio - image - poster detectedContentType: anyOf: - type: string minLength: 0 maxLength: 160 - type: 'null' measuredBytes: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' measuredDurationMs: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' width: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' height: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' hasVideoTrack: type: - boolean - 'null' hasAudioTrack: type: - boolean - 'null' transcript: anyOf: - type: object properties: mediaId: 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}$ language: type: string minLength: 2 maxLength: 16 source: type: string enum: - captions - automatic_captions segmentCount: type: integer minimum: 0 maximum: 9007199254740991 required: - mediaId - language - source - segmentCount additionalProperties: false - type: 'null' creativeSpec: anyOf: - type: object properties: version: type: string const: creative-spec.v0 hook: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' shots: maxItems: 200 type: array items: type: object properties: startMs: type: integer minimum: 0 maximum: 9007199254740991 endMs: type: integer minimum: 0 maximum: 9007199254740991 description: type: string minLength: 0 maxLength: 500 required: - startMs - endMs - description additionalProperties: false pacing: anyOf: - type: object properties: averageShotMs: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 cutsPerMinute: type: number minimum: 0 required: - averageShotMs - cutsPerMinute additionalProperties: false - type: 'null' callToAction: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' generationPrompt: anyOf: - type: string minLength: 0 maxLength: 10000 - type: 'null' required: - version - hook - shots - pacing - callToAction - generationPrompt additionalProperties: false - type: 'null' aiProvenance: anyOf: - type: object properties: version: type: string const: ai-provenance.v0 aiGeneratedScore: anyOf: - type: number minimum: 0 maximum: 1 - type: 'null' modelGuess: anyOf: - type: string minLength: 0 maxLength: 160 - type: 'null' c2paPresent: type: - boolean - 'null' required: - version - aiGeneratedScore - modelGuess - c2paPresent additionalProperties: false - type: 'null' required: - mediaKind - detectedContentType - measuredBytes - measuredDurationMs - width - height - hasVideoTrack - hasAudioTrack - transcript - creativeSpec - aiProvenance additionalProperties: false - type: 'null' provenance: anyOf: - type: object properties: sourceRouteId: 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}$ routeContractVersion: type: string minLength: 1 maxLength: 32 acquiredAt: 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)$ required: - sourceRouteId - routeContractVersion - acquiredAt additionalProperties: false - type: 'null' mediaHold: anyOf: - type: object properties: referenceId: 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}$ mediaId: 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}$ expiresAt: 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)$ reason: type: string enum: - ingestion_request - explicit_extension revision: type: integer minimum: 0 maximum: 9007199254740991 required: - referenceId - mediaId - expiresAt - reason - revision additionalProperties: false - type: 'null' mediaExpiredAt: 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' required: - id - workspaceId - canonicalContentId - sourceIngestionId - platform - canonicalUrl - state - mediaAvailability - failureCode - retryable - createdAt - updatedAt - revision - sourceObserved - humanAuthored - primaryMediaId - posterMediaId - machineDerived - provenance - mediaHold - mediaExpiredAt 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 ````