vCita File Relations API

The File Relations API from vCita — 2 operation(s) for file relations.

GitHub OpenAPI

Operations 3

POST /v3/assets/file_relations Create a file relation #
GET /v3/assets/file_relations Get file relations by entity #
DELETE /v3/assets/file_relations/{uid} Delete a file relation #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/vcita:vcita-file-relations-api"
All apis
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.

Get an API 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 Specification

vcita-file-relations-api-openapi.yml Raw ↑
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