> ## 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. # Update a reference's title, notes and tags ## OpenAPI ````yaml /api-reference/openapi.json patch /v1/references/{referenceId} openapi: 3.1.0 info: title: Refmatter API version: 0.1.0 description: >- Public social data API: one request turns a TikTok, Instagram, YouTube or Meta Ad Library link into structured data; import it to keep verified media, a transcript and provenance. servers: - url: https://api.refmatter.com security: - bearerApiKey: [] tags: - name: workspaces x-group: Workspaces description: Manage workspaces and review their usage. - name: imports x-group: Imports description: Start imports from source URLs and check their progress. - name: urls x-group: URLs description: Identify the platform and object represented by a social URL. - name: items x-group: Items description: List and look up items from supported platforms. - name: accounts x-group: Accounts description: Look up accounts and retrieve their current data. - name: comments x-group: Comments description: List comments for supported items. - name: search x-group: Search description: Search supported platforms for items or accounts. - name: references x-group: References description: Manage saved references and their transcripts and media. - name: media x-group: Media description: Create short-lived access to stored media. - name: sourceRoutes x-group: Sources description: List the supported platforms and objects with their limits. paths: /v1/references/{referenceId}: patch: tags: - references summary: Update a reference's title, notes and tags operationId: referencesUpdate parameters: - name: referenceId in: path required: true description: Opaque reference identifier schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReferenceUpdate' responses: '200': description: Updated 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: Service or dependency unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - bearerApiKey: [] components: schemas: ReferenceUpdate: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: revision: type: integer minimum: 0 maximum: 9007199254740991 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: - revision additionalProperties: false 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' sourceImportId: 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 - instagram - meta_ad_library 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 - insufficient_credits - 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' creatives: maxItems: 30 type: array items: type: object properties: index: type: integer minimum: 0 maximum: 9007199254740991 kind: type: string enum: - image - video 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}$ contentType: anyOf: - type: string minLength: 0 maxLength: 160 - type: 'null' byteSize: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' required: - index - kind - mediaId - contentType - byteSize additionalProperties: false 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: - import_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 - sourceImportId - 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 - insufficient_credits - 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 ````