vCita File Relations API
The File Relations API from vCita — 2 operation(s) for file relations.
The File Relations API from vCita — 2 operation(s) for file relations.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/vcita:vcita-file-relations-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Assets File Relations API
description: Unified OpenAPI specification for assets domain
version: '3.0'
x-generated:
sourceFiles:
- files.json
- legacy_documents.json
pathNormalizations: []
pathConflicts: []
componentConflicts:
- type: schema
name: ErrorResponse
resolution: Renamed to ErrorResponse_legacy_documents
files:
- merged
- legacy_documents.json
totalPaths: 11
totalComponents: 9
servers:
- url: https://api.vcita.biz
description: Unified API Gateway server
tags:
- name: File Relations
paths:
/v3/assets/file_relations:
post:
operationId: FileRelationsController_create
summary: Create a file relation
description: 'Links an existing file to a business entity (e.g., an invoice, message, or meeting). The referenced file must already exist and must not be infected, failed, or deleted; linking is allowed while the file is still processing (''pending'', ''scanning'') as well as once ready (''scanned'', ''uploaded'', ''linked''). If the file is later found infected or fails processing, any relation created for it is retracted. Once a file has at least one active relation its status becomes ''linked'', protecting it from cleanup.
The caller must have access to the related entity: a Staff token is checked directly against the entity. A Client token is checked by querying the client''s own activity on that entity — the entity must appear in the client''s activity feed (matched by message text for entity_type=''message'', or by activity type for every other entity type). Any error or timeout from that check is treated as no access (fails closed).
For **Client tokens**, the client_uid is derived from the token and any value supplied in the body is ignored. For **Staff tokens**, client_uid may be provided to associate the relation with a specific client; omitting it returns a 400.
Available for **Staff and Client tokens**.'
tags:
- File Relations
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFileRelationRequest'
responses:
'201':
description: Relation created successfully
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Response'
- properties:
data:
type: object
description: Represents a relationship between a file and a business entity (e.g., invoice, message, meeting). This allows files to be attached to various entities across the platform. When a file has at least one active relation, its status becomes 'linked' and it is protected from cleanup jobs.
properties:
uid:
type: string
readOnly: true
description: Unique identifier for the file-entity relation record (e.g., "rel_123abc").
file_uid:
type: string
description: Unique identifier of the file being linked (e.g., "file_456def"). Must reference an existing file with status 'scanned', 'uploaded', or 'linked'.
entity_type:
type: string
enum:
- message
- invoice
- payment
- meeting
- estimate
description: 'Type of entity the file is attached to. **message**: Email message. **invoice**: Invoice document. **payment**: Payment record. **meeting**: Scheduled meeting/appointment. **estimate**: Estimate/quote document.'
entity_uid:
type: string
description: Unique identifier of the entity the file is attached to (e.g., "inv_789xyz" for an invoice, "msg_123abc" for a message).
business_uid:
type: string
readOnly: true
description: Unique identifier of the business that owns both the file and the entity (e.g., "biz_456xyz"). Inherited from the file record.
client_uid:
type: string
nullable: true
description: Unique identifier of the client associated with this relation, if applicable (e.g., "client_789abc"). Used for client-specific files like uploaded documents or images. Null for business-level files.
created_at:
type: string
format: date-time
readOnly: true
description: Timestamp when the relation was created, in ISO 8601 format (e.g., "2026-01-27T10:35:00Z").
updated_at:
type: string
format: date-time
readOnly: true
description: Timestamp when the relation was last updated, in ISO 8601 format (e.g., "2026-01-27T10:35:30Z").
deleted_at:
type: string
format: date-time
nullable: true
readOnly: true
description: Timestamp when the relation was soft deleted, in ISO 8601 format (e.g., "2026-01-27T12:00:00Z"). Null if the relation is still active. When all relations for a file are deleted, the file may become eligible for cleanup.
file:
type: object
readOnly: true
nullable: true
description: Details of the linked file, included when relations are fetched by entity. Omitted on relation creation.
properties:
name:
type: string
description: Original filename including extension (e.g., "invoice_2026_Q1.pdf").
status:
type: string
enum:
- pending
- scanning
- scanned
- uploaded
- infected
- failed
- linked
- deleted
description: Current processing status of the linked file.
content_type:
type: string
description: MIME type of the linked file (e.g., "application/pdf", "image/jpeg").
size:
type: integer
format: int64
description: File size in bytes (e.g., 2048576).
url:
type: string
format: uri
nullable: true
description: Pre-signed S3 URL for downloading the original file. Null for pending/infected files.
thumbnail_url:
type: string
format: uri
nullable: true
description: Pre-signed S3 URL for the thumbnail scaled to 400px height, with width following the source's aspect ratio (never upscaled). Available for images and, as a poster frame, for videos, after successful processing. Null for other file types or pending uploads.
thumbnail_small_url:
type: string
format: uri
nullable: true
description: Pre-signed S3 URL for the thumbnail scaled to 150px height, with width following the source's aspect ratio (never upscaled). Available for images and, as a poster frame, for videos, after successful processing. Null for other file types or pending uploads.
metadata:
type: object
nullable: true
description: Optional JSON object containing arbitrary key-value pairs for additional file metadata.
created_at:
type: string
format: date-time
description: Timestamp when the file record was created, in ISO 8601 format.
updated_at:
type: string
format: date-time
description: Timestamp when the file record was last updated, in ISO 8601 format.
required:
- uid
- file_uid
- entity_type
- entity_uid
- business_uid
- created_at
- updated_at
example:
uid: rel_abc123def456
file_uid: file_789xyz
entity_type: invoice
entity_uid: inv_456abc
business_uid: biz_123xyz
client_uid: client_789def
created_at: '2026-01-27T10:35:00Z'
updated_at: '2026-01-27T10:35:00Z'
deleted_at: null
file:
name: invoice_2026_Q1.pdf
status: linked
content_type: application/pdf
size: 2048576
url: https://s3.amazonaws.com/files-bucket/biz_123xyz/2026/01/27/file_789xyz/original?signature=abc123...
thumbnail_url: https://s3.amazonaws.com/files-bucket/biz_123xyz/2026/01/27/file_789xyz/thumb_400.jpg?signature=def456...
thumbnail_small_url: https://s3.amazonaws.com/files-bucket/biz_123xyz/2026/01/27/file_789xyz/thumb_150.jpg?signature=ghi789...
metadata:
source: chat
created_at: '2026-01-27T10:30:00Z'
updated_at: '2026-01-27T10:30:45Z'
'400':
description: Bad request - either the file is infected, failed, or deleted (cannot be linked), or client_uid was omitted on a Staff-token request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized - Invalid or missing authentication token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden - No access to the related entity
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found - File does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Conflict - A relation between this file and entity already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Unprocessable Entity - Validation error in request data
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Files: []
get:
operationId: FileRelationsController_findByEntity
summary: Get file relations by entity
description: 'Retrieves the file relations for a given entity, each including the linked file''s details. Results are paginated.
Staff access is scoped to the linked entity: a staff sees relations for any entity they can access, regardless of who uploaded the file. Client access is scoped to the client''s own relations. In both cases, no access to the entity is not an error — it returns an empty list (`total: 0`), indistinguishable from the entity genuinely having no relations.
Available for **Staff and Client tokens**.'
tags:
- File Relations
parameters:
- name: entity_type
in: query
required: true
description: Type of entity to fetch relations for (e.g., "invoice", "message", "meeting").
schema:
type: string
enum:
- message
- invoice
- payment
- meeting
- estimate
- name: entity_uid
in: query
required: true
description: Unique identifier of the entity to fetch relations for (e.g., "inv_123abc").
schema:
type: string
- name: page
in: query
required: false
description: 'Page number for pagination (default: 1).'
schema:
type: integer
minimum: 1
default: 1
- name: per_page
in: query
required: false
description: 'Number of relations per page (default: 20).'
schema:
type: integer
minimum: 1
default: 20
responses:
'200':
description: Relations retrieved successfully
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Response'
- properties:
data:
$ref: '#/components/schemas/FileRelationsResponse'
'401':
description: Unauthorized - Invalid or missing authentication token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Files: []
/v3/assets/file_relations/{uid}:
delete:
operationId: FileRelationsController_deleteRelation
summary: Delete a file relation
description: 'Soft deletes a single file relation by its unique identifier. If it was the file''s last active relation, the file may become eligible for cleanup.
A Staff token must have access to the related entity (same check as create). A Client token may only delete a relation for a file it created itself.
Available for **Staff and Client tokens**.'
tags:
- File Relations
parameters:
- name: uid
in: path
required: true
description: Unique identifier of the file relation to delete (e.g., "rel_abc123def456").
schema:
type: string
responses:
'204':
description: Relation deleted successfully (soft delete). No response body.
'401':
description: Unauthorized - Invalid or missing authentication token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden - No access to the related entity (Staff tokens), or the relation's file was not created by this client (Client tokens)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Not Found - File relation does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Files: []
components:
schemas:
FileRelationsResponse:
type: object
properties:
file_relations:
type: array
items:
type: object
description: Represents a relationship between a file and a business entity (e.g., invoice, message, meeting). This allows files to be attached to various entities across the platform. When a file has at least one active relation, its status becomes 'linked' and it is protected from cleanup jobs.
properties:
uid:
type: string
readOnly: true
description: Unique identifier for the file-entity relation record (e.g., "rel_123abc").
file_uid:
type: string
description: Unique identifier of the file being linked (e.g., "file_456def"). Must reference an existing file with status 'scanned', 'uploaded', or 'linked'.
entity_type:
type: string
enum:
- message
- invoice
- payment
- meeting
- estimate
description: 'Type of entity the file is attached to. **message**: Email message. **invoice**: Invoice document. **payment**: Payment record. **meeting**: Scheduled meeting/appointment. **estimate**: Estimate/quote document.'
entity_uid:
type: string
description: Unique identifier of the entity the file is attached to (e.g., "inv_789xyz" for an invoice, "msg_123abc" for a message).
business_uid:
type: string
readOnly: true
description: Unique identifier of the business that owns both the file and the entity (e.g., "biz_456xyz"). Inherited from the file record.
client_uid:
type: string
nullable: true
description: Unique identifier of the client associated with this relation, if applicable (e.g., "client_789abc"). Used for client-specific files like uploaded documents or images. Null for business-level files.
created_at:
type: string
format: date-time
readOnly: true
description: Timestamp when the relation was created, in ISO 8601 format (e.g., "2026-01-27T10:35:00Z").
updated_at:
type: string
format: date-time
readOnly: true
description: Timestamp when the relation was last updated, in ISO 8601 format (e.g., "2026-01-27T10:35:30Z").
deleted_at:
type: string
format: date-time
nullable: true
readOnly: true
description: Timestamp when the relation was soft deleted, in ISO 8601 format (e.g., "2026-01-27T12:00:00Z"). Null if the relation is still active. When all relations for a file are deleted, the file may become eligible for cleanup.
file:
type: object
readOnly: true
nullable: true
description: Details of the linked file, included when relations are fetched by entity. Omitted on relation creation.
properties:
name:
type: string
description: Original filename including extension (e.g., "invoice_2026_Q1.pdf").
status:
type: string
enum:
- pending
- scanning
- scanned
- uploaded
- infected
- failed
- linked
- deleted
description: Current processing status of the linked file.
content_type:
type: string
description: MIME type of the linked file (e.g., "application/pdf", "image/jpeg").
size:
type: integer
format: int64
description: File size in bytes (e.g., 2048576).
url:
type: string
format: uri
nullable: true
description: Pre-signed S3 URL for downloading the original file. Null for pending/infected files.
thumbnail_url:
type: string
format: uri
nullable: true
description: Pre-signed S3 URL for the thumbnail scaled to 400px height, with width following the source's aspect ratio (never upscaled). Available for images and, as a poster frame, for videos, after successful processing. Null for other file types or pending uploads.
thumbnail_small_url:
type: string
format: uri
nullable: true
description: Pre-signed S3 URL for the thumbnail scaled to 150px height, with width following the source's aspect ratio (never upscaled). Available for images and, as a poster frame, for videos, after successful processing. Null for other file types or pending uploads.
metadata:
type: object
nullable: true
description: Optional JSON object containing arbitrary key-value pairs for additional file metadata.
created_at:
type: string
format: date-time
description: Timestamp when the file record was created, in ISO 8601 format.
updated_at:
type: string
format: date-time
description: Timestamp when the file record was last updated, in ISO 8601 format.
required:
- uid
- file_uid
- entity_type
- entity_uid
- business_uid
- created_at
- updated_at
example:
uid: rel_abc123def456
file_uid: file_789xyz
entity_type: invoice
entity_uid: inv_456abc
business_uid: biz_123xyz
client_uid: client_789def
created_at: '2026-01-27T10:35:00Z'
updated_at: '2026-01-27T10:35:00Z'
deleted_at: null
file:
name: invoice_2026_Q1.pdf
status: linked
content_type: application/pdf
size: 2048576
url: https://s3.amazonaws.com/files-bucket/biz_123xyz/2026/01/27/file_789xyz/original?signature=abc123...
thumbnail_url: https://s3.amazonaws.com/files-bucket/biz_123xyz/2026/01/27/file_789xyz/thumb_400.jpg?signature=def456...
thumbnail_small_url: https://s3.amazonaws.com/files-bucket/biz_123xyz/2026/01/27/file_789xyz/thumb_150.jpg?signature=ghi789...
metadata:
source: chat
created_at: '2026-01-27T10:30:00Z'
updated_at: '2026-01-27T10:30:45Z'
description: Array of file relations, each including the linked file's details
required:
- file_relations
Response:
type: object
properties:
success:
type: boolean
data:
type: object
required:
- success
- data
CreateFileRelationRequest:
type: object
properties:
file_uid:
type: string
description: Unique identifier of the file to link (e.g., "file_123abc"). Must reference an existing file that is not infected, failed, or deleted; linking is allowed while the file is still processing ('pending', 'scanning') as well as once ready ('scanned', 'uploaded', 'linked').
entity_type:
type: string
enum:
- message
- invoice
- payment
- meeting
- estimate
description: Type of entity the file is linked to (e.g., "message", "invoice").
entity_uid:
type: string
description: Unique identifier of the entity the file is linked to (e.g., "inv_123abc").
client_uid:
type: string
description: Client UID to associate with the relation (e.g., "client_789abc"). Required for **Staff tokens** (omitting it returns a 400 CLIENT_UID_REQUIRED); ignored for **Client tokens**, where it is derived from the token instead.
required:
- file_uid
- entity_type
- entity_uid
ErrorResponse:
type: object
properties:
success:
type: boolean
errors:
type: array
items:
type: object
properties:
field:
type: string
description: The name of the field that had an error (for validation errors) (e.g., "name", "file").
code:
type: string
description: The error code (for validation errors) (e.g., "FILE_REQUIRED", "VALIDATION_ERROR").
description:
type: string
description: A description of the error (for validation errors) (e.g., "File is required").
securitySchemes:
Files:
type: http
scheme: bearer
Bearer:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Provide a valid bearer token in the Authorization header. Example: ''Authorization: Bearer {app_token}'''
x-provenance:
method: searched
source: https://developers.intandem.tech:443/reference
harvested: '2026-11-15'
tool: harvest-readme-openapi.py
note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
assembled_from:
- https://developers.intandem.tech/reference/filerelationscontroller_create.md
- https://developers.intandem.tech/reference/filerelationscontroller_deleterelation.md
- https://developers.intandem.tech/reference/filerelationscontroller_findbyentity.md
- https://developers.intandem.tech/reference/filescontroller_delete.md
- https://developers.intandem.tech/reference/filescontroller_findall.md
- https://developers.intandem.tech/reference/filescontroller_findone.md
- https://developers.intandem.tech/reference/filescontroller_upload.md
- https://developers.intandem.tech/reference/get_client-api-v1-portals-business-uid-contact-get-form-1.md
- https://developers.intandem.tech/reference/get_client-api-v1-portals-business-uid-share-documents-form-get-form-1.md
- https://developers.intandem.tech/reference/get_platform-v1-clients-client-id-documents-1.md
- https://developers.intandem.tech/reference/get_platform-v1-forms.md
- https://developers.intandem.tech/reference/get_v2-search-search-docuforms-1.md
- https://developers.intandem.tech/reference/post_client-api-v1-portals-business-uid-contact-submit-1.md
- https://developers.intandem.tech/reference/post_client-api-v1-portals-business-uid-share-documents-form-submit-1.md
- https://developers.intandem.tech/reference/put_platform-v1-forms.md
- https://developers.intandem.tech:443/reference/filerelationscontroller_create.md
- https://developers.intandem.tech:443/reference/filerelationscontroller_deleterelation.md
- https://developers.intandem.tech:443/reference/filerelationscontroller_findbyentity.md
- https://developers.intandem.tech:443/reference/filescontroller_delete.md
- https://developers.intandem.tech:443/reference/filescontroller_findall.md
- https://developers.intandem.tech:443/reference/filescontroller_findone.md
- https://developers.intandem.tech:443/reference/filescontroller_upload.md
- https://developers.intandem.tech:443/reference/get_client-api-v1-portals-business-uid-contact-get-form-1.md
- https://developers.intandem.tech:443/reference/get_client-api-v1-portals-business-uid-share-documents-form-get-form-1.md
- https://developers.intandem.tech:443/reference/get_platform-v1-clients-client-id-documents-1.md
- https://developers.intandem.tech:443/reference/get_platform-v1-forms.md
- https://developers.intandem.tech:443/reference/get_v2-search-search-docuforms-1.md
- https://developers.intandem.tech:443/reference/post_client-api-v1-portals-business-uid-contact-submit-1.md
- https://developers.intandem.tech:443/reference/post_client-api-v1-portals-business-uid-share-documents-form-submit-1.md
- https://developers.intandem.tech:443/reference/put_platform-v1-forms.md
merge:
pages: 30
deduped: 74
conflicts_kept_first: 0