Mavenlink User File Associations API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Kantata OX API Documentation User File Associations API
  description: Kantata OX's API provides access to the majority of Kantata OX's data model.
  termsOfService: https://www.kantata.com/terms-of-use
  contact:
    name: Kantata OX Support
    url: https://knowledge.kantata.com/hc/en-us
  license:
    name: COPYRIGHT © 2026 Kantata, Inc.
    url: https://www.kantata.com/terms-of-use
  x-logo:
    url: https://theme.zdassets.com/theme_assets/56104/04e93064d309f75d054b8cee885d1ea51e9be8f7.png
    backgroundColor: '#FFFFFF'
    altText: Kantata OX API Documentation
    href: https://developer.kantata.com
servers:
- url: https://api.mavenlink.com/api/v1
tags:
- name: User File Associations
  description: 'User File Associations in Kantata OX act as a join object between Users, Workspaces, and

    Attachments / Google Documents.'
paths:
  /user_file_associations:
    get:
      summary: Fetching a list of User File Associations
      description: 'This endpoint returns structured User File Association objects.

        As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array

        and will be indexed by ID in the `user_file_associations` top-level JSON key.

        Please see our Response Format section for more information.'
      operationId: Get User File Associations
      tags:
      - User File Associations
      parameters:
      - in: query
        name: filename
        description: Only includes file associations with matching filenames.
        schema:
          type: string
      - in: query
        name: include
        description: 'Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.

          - `asset_object` (polymorphic) - When included, the polymorphic `asset_object_ref` struct will reference the attachment or

          Google document for which the user file association belongs. This will be a a two-key JSON

          object with "ID" and "key", where the "key" will be "attachments" or "google_documents".

          - `post` (Post) - The post to which the user file association belongs.

          - `workspace` (Workspace) - References the project to which the user file association belongs.'
        schema:
          type: string
      - in: query
        name: only
        description: 'Allows you to request one or more resources directly by ID. Multiple IDs can be supplied

          in a comma separated list, like `GET /api/v1/workspaces.json?only=5,6,7`.'
        schema:
          type: string
      - in: query
        name: order
        description: 'Supply `order` with the name of a valid sort field for the endpoint and a direction.


          Valid values: `created_at:asc` and `created_at:desc`.'
        schema:
          type: string
          default: created_at:desc
      - in: query
        name: page
        schema:
          type: integer
          format: int32
          default: 1
      - in: query
        name: per_page
        schema:
          type: integer
          format: int32
          default: 20
          maximum: 200
      - in: query
        name: workspace_id
        description: Only includes file associations from the specified project.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: A list of User File Associations have been retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    format: int32
                  meta:
                    type: object
                    properties:
                      count:
                        type: integer
                        format: int32
                      page_count:
                        type: integer
                        format: int32
                      page_number:
                        type: integer
                        format: int32
                      page_size:
                        type: integer
                        format: int32
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        id:
                          type: string
                  user_file_associations:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/UserFileAssociation'
                  posts:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Post'
                  workspaces:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/Workspace'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Forbidden request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Page Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '503':
          description: Service is unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
components:
  schemas:
    Error:
      type: object
      properties:
        type:
          type: string
        message:
          type: string
    Workspace:
      title: Workspace
      description: Workspaces (also called projects) represent the space in which Kantata OX users plan, communicate, and collaborate.
      type: object
      properties:
        access_level:
          type: string
          description: Whether the project is open, and who can join it. Possible values are `invitation`, `open`, and `admin`.
        account_color_id:
          type: string
          description: '`account_color_id` will only be included in the response if `account_color` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        account_id:
          type: integer
          format: int32
          description: The ID of the account which the project is in.
        account_insights_mapping_ids:
          type: array
          items:
            type: string
          description: '`account_insights_mapping_ids` will only be included in the response if `account_insights_mappings` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        actual_fees_includes_additional_line_items:
          type: boolean
          description: 'Whether invoice additional items are included in actual fees calculations for the project.

            Visible when the authenticated user is a project administrator and is on the account that the project is on.'
        actual_fees_includes_expenses:
          type: boolean
          description: 'Whether expenses are included in actual fees calculations for the project.

            Visible when the authenticated user is a project administrator and is on the account that the project is on.'
        approver_id:
          type: string
          description: '`approver_id` will only be included in the response if `approver` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        approver_ids:
          type: array
          items:
            type: string
          description: '`approver_ids` will only be included in the response if `approvers` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        archived:
          type: boolean
          description: Whether the project is archived.
        billable_minutes:
          type: integer
          format: int32
          description: 'The total amount of billable time entries, in minutes. Only visible if the authenticated user has financial access in the project and is on the provider team.

            Visible when the authenticated user can see total time approved in the project.


            Only returned when requested through the optional_fields param.'
        billing_milestone_ids:
          type: array
          items:
            type: string
          description: '`billing_milestone_ids` will only be included in the response if `billing_milestones` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        budget_remaining:
          type: string
          description: 'The amount of the project budget remaining.

            Visible when the authenticated user is on the provider team and can either see reports on the account or has financial access in the project.'
        budget_used:
          type: string
          description: 'The amount of the project budget that has been used.

            Visible when the authenticated user is on the provider team and can either see reports on the account or has financial access in the project.'
        budget_used_in_cents:
          type: integer
          format: int32
          description: 'The amount of the project budget that has been used, in the subunits of the currency (e.g. cents for USD).

            Visible when the authenticated user is on the provider team and can either see reports on the account or has financial access in the project.'
        budgeted:
          type: boolean
          description: Whether the project is budgeted.
        can_create_line_items:
          type: boolean
          description: Whether the authenticated user can create line items in the project (i.e. time entries, expenses, fixed fee items, or additional items).
        can_invite:
          type: boolean
          description: Whether the authenticated user can invite others to the project.
        change_orders_enabled:
          type: boolean
          description: Whether change orders are enabled in the project.
        client_lead_name:
          type: string
          description: 'The name of the team lead for the client side of the project.

            Only returned when requested through the optional_fields param.'
        client_role_name:
          type: string
          description: The client team name.
        consultant_role_name:
          type: string
          description: The provider team name.
        created_at:
          type: string
          format: date-time
          description: The date the project was created.
        creator_id:
          type: string
          description: '`creator_id` will only be included in the response if `creator` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        currency:
          type: string
          description: The currency of the project. Only visible if the authenticated user has financial access in the project.
        currency_base_unit:
          type: integer
          format: int32
          description: The base unit of the currency of the project. For example, the base unit for USD is 100.
        currency_symbol:
          type: string
          description: The [ISO symbol](https://knowledge.kantata.com/hc/en-us/articles/360041576473) for the currency of the project. For example, `USD`.
        current_status_report_id:
          type: string
          description: '`current_status_report_id` will only be included in the response if `current_status_report` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        current_user_participation_id:
          type: string
          description: '`current_user_participation_id` will only be included in the response if `current_user_participation` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        custom_field_value_ids:
          type: array
          items:
            type: string
          description: '`custom_field_value_ids` will only be included in the response if `custom_field_values` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        default_rate:
          type: string
          description: The default billing rate for the project.
        description:
          type: string
          description: The description of the project.
        due_date:
          type: string
          format: date
          description: The due date of the project.
        effective_due_date:
          type: string
          format: date
          description: The due date of the project (deprecated).
        estimated_minutes:
          type: integer
          format: int32
          description: 'The total task estimated minutes of the project.

            Visible when the authenticated user can see reports on the account or has financial access in the project.


            Only returned when requested through the optional_fields param.'
        exclude_archived_stories_percent_complete:
          type: boolean
          description: Whether archived tasks are excluded from the calculation of the project completion percentage.
        expenses_in_burn_rate:
          type: boolean
          description: 'Whether both expenses and invoice additional items are included in the actual fees calculation for the project. This field is the `AND` of `actual_fees_includes_expenses` and `actual_fees_includes_additional_line_items`.

            Visible when the authenticated user is a project administrator and is on the account that the project is on.'
        external_link:
          type: object
          description: 'A link that displays within the project workspace. Requires the Project Button facilitated feature.

            Visible when the workspace has the project button feature enabled.'
          properties:
            url:
              type: string
              description: 'The URL of the link.

                Visible when the workspace has the project button feature enabled.'
            text:
              type: string
              description: 'The button text.

                Visible when the workspace has the project button feature enabled.'
        external_reference_ids:
          type: array
          items:
            type: string
          description: '`external_reference_ids` will only be included in the response if `external_references` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        financial_viewer_ids:
          type: array
          items:
            type: string
          description: '`financial_viewer_ids` will only be included in the response if `financial_viewers` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        has_active_expense_report_submissions:
          type: boolean
          description: Whether the project has active expense report submissions.
        has_active_timesheet_submissions:
          type: boolean
          description: Whether the project has active timesheet submissions.
        has_budget_access:
          type: boolean
          description: Whether the authenticated user has budget access in the project.
        incoming_email_address:
          type: string
          description: 'The email address for the project—unique to the authenticated user—which can be used to post to the project''s Activity Feed via email.

            Visible when the authenticated user is a project administrator and is on the account that the project is on.


            Only returned when requested through the optional_fields param.'
        lock_date:
          type: string
          format: date
          description: 'The line item lock date for the account the project is on, if any.

            Only returned when requested through the optional_fields param.'
        minutes_logged:
          type: integer
          format: int32
          description: 'The total minutes logged on the project, including time adjustments. Only visible if the authenticated user has financial access in the project and is on the provider team.

            Visible when the authenticated user can see total time approved in the project.


            Only returned when requested through the optional_fields param.'
        next_uncompleted_milestone_id:
          type: string
          description: '`next_uncompleted_milestone_id` will only be included in the response if `next_uncompleted_milestone` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        non_billable_minutes:
          type: integer
          format: int32
          description: 'The total of all non-billable time entries in minutes, only included if the current user has financial access and is a maven in the project.

            Visible when the authenticated user can see total time approved in the project.


            Only returned when requested through the optional_fields param.'
        over_budget:
          type: boolean
          description: 'Whether the project is over budget. Only visible if the authenticated user has financial access in the project.

            Visible when the authenticated user is a project administrator and is on the account that the project is on.'
        participant_ids:
          type: array
          items:
            type: string
          description: '`participant_ids` will only be included in the response if `participants` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        participation_ids:
          type: array
          items:
            type: string
          description: '`participation_ids` will only be included in the response if `participations` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        percent_of_budget_used:
          type: integer
          format: int32
          description: 'The percent of the project budget used.

            Visible when the authenticated user is on the provider team and can either see reports on the account or has financial access in the project.'
        percentage_complete:
          type: integer
          format: int32
          description: The completion percentage of the project, calculated from the completion percentage of the stories (tasks), including archived stories.
        permissions:
          type: object
          description: Various project permissions for the authenticated user.
          properties:
            can_upload_files:
              type: boolean
              description: Whether the authenticated user can upload files to the project.
            can_private_message:
              type: boolean
              description: Whether the authenticated user can send private messages in the project.
            can_join:
              type: boolean
              description: Whether the authenticated user can join the project.
            is_participant:
              type: boolean
              description: Whether the authenticated user is participating in the project.
            access_level:
              type: string
              description: The authenticated user’s permission level in the project.
            team_lead:
              type: boolean
              description: Whether the authenticated user is a team lead in the project.
            user_is_client:
              type: boolean
              description: Whether the authenticated user is a client in the project.
            can_change_price:
              type: boolean
              description: Whether the authenticated user can change the price (budget) of the project.
            can_change_story_billable:
              type: boolean
              description: Whether the authenticated user can change the billable status of stories (tasks) in the project.
            can_post:
              type: boolean
              description: Whether the authenticated user has post permissions in the project.
            can_edit:
              type: boolean
              description: Whether the authenticated user has edit permissions in the project.
            restricted:
              type: boolean
              description: Whether the authenticated user is a restricted user in the project.
            can_see_financials:
              type: boolean
              description: Whether the authenticated user has financial access in the project.
            is_guest_on_project:
              type: boolean
              description: Returns true if the authenticated user can view projects without joining. Otherwise, returns false.
        possible_approver_ids:
          type: array
          items:
            type: string
          description: '`possible_approver_ids` will only be included in the response if `possible_approvers` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        posts_require_privacy_decision:
          type: boolean
          description: Whether posts are private (`true`) or shared with all project participants (`false`) by default.
        price:
          type: string
          description: 'The project budget.

            Visible when the authenticated user can see reports on the account or has financial access in the project.'
        price_in_cents:
          type: integer
          format: int32
          description: 'The project budget, in the subunits of the currency (e.g. cents for USD).

            Visible when the authenticated user can see reports on the account or has financial access in the project.'
        primary_counterpart_id:
          type: string
          description: '`primary_counterpart_id` will only be included in the response if `primary_counterpart` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        primary_maven_id:
          type: string
          description: '`primary_maven_id` will only be included in the response if `primary_maven` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        primary_workspace_group_id:
          type: string
          description: '`primary_workspace_group_id` will only be included in the response if `primary_workspace_group` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        provider_lead_name:
          type: string
          description: 'The name of the team lead for the provider side of the project.

            Only returned when requested through the optional_fields param.'
        rate_card_id:
          type: integer
          format: int32
          description: The ID of the rate card for the project.
        require_expense_approvals:
          type: boolean
          description: Whether expense approvals are required in the project.
        require_notes_on_time_entries:
          type: boolean
          description: Whether notes are required on time entries logged against this project.
        require_time_approvals:
          type: boolean
          description: Whether time approvals are required in the project.
        revenue_recognition_method_id:
          type: string
          description: 'The ID of the project''s revenue recognition method, which determines how the project''s revenue is recognized and accounted for. The ID is a composite ID made up of a numerical ID (unique to each account), a colon, and the method type. For example `123:percent_complete`.

            Only returned when requested through the optional_fields param.'
        revenue_recognition_method_name:
          type: string
          description: 'The name of the project''s revenue recognition method, which determines how the project''s revenue is recognized and accounted for.

            Only returned when requested through the optional_fields param.'
        stage:
          type: string
          description: 'The stage of the project. Possible values are `estimate` or `project`.

            Only returned when requested through the optional_fields param.'
        start_date:
          type: string
          format: date
          description: The start date of the project.
        status:
          type: object
          description: 'A hash containing the status of the project.

            Visible when the authenticated user can view the project status.'
          properties:
            color:
              type: string
              description: 'The status color of the project (e.g. ''red'').

                Visible when the authenticated user can view the project status.'
            key:
              type: string
              description: 'The status key of the project (e.g. ''501'').

                Visible when the authenticated user can view the project status.'
            message:
              type: string
              description: 'The status message of the project (e.g. ''Cancelled'').

                Visible when the authenticated user can view the project status.'
        status_report_ids:
          type: array
          items:
            type: string
          description: '`status_report_ids` will only be included in the response if `status_reports` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        stories_are_fixed_fee_by_default:
          type: boolean
          description: 'Whether stories (tasks) are fixed fee by default.

            Visible when the authenticated user is a project administrator and is on the account that the project is on.'
        target_margin:
          type: number
          format: float
          description: 'The target margin of the project.

            Visible when the authenticated user is on the provider team and can either see reports on the account or has financial access in the project.'
        task_status_set_id:
          type: string
          description: The ID of the task status set assigned to the workspace.
        task_status_set_name:
          type: string
          description: The name of the task status set assigned to the workspace.
        task_statuses:
          type: array
          items:
            type: string
          description: The task statuses available in the workspace.
        tasks_default_non_billable:
          type: boolean
          description: Whether stories (tasks) are non-billable by default.
        time_trackable:
          type: boolean
          description: Whether time can be tracked against this project and its tasks.
        timesheet_submission_ids:
          type: array
          items:
            type: string
          description: '`timesheet_submission_ids` will only be included in the response if `timesheet_submissions` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        title:
          type: string
          description: The title of the project.
        total_expenses_in_cents:
          type: integer
          format: int32
          description: 'The total amount of expenses on the project, in the subunits of the currency (e.g. cents for USD).

            Visible when the authenticated user is a project administrator and is on the account that the project is on.'
        total_invoiced:
          type: string
          description: 'The total amount invoiced, in the subunits of the currency (e.g. cents for USD).

            Visible when the authenticated user can see reports on the account or has financial access in the project.


            Only returned when requested through the optional_fields param.'
        total_minutes_approved:
          type: integer
          format: int32
          description: 'The total amount of approved time entries, in minutes. Only visible if the authenticated user has financial access in the project and is on the provider team.

            Visible when the authenticated user can see total time approved in the project.


            Only returned when requested through the optional_fields param.'
        updated_at:
          type: string
          format: date-time
          description: The date that the project was last updated.
        workspace_group_ids:
          type: array
          items:
            type: string
          description: '`workspace_group_ids` will only be included in the response if `workspace_groups` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        workspace_invoice_preference_id:
          type: integer
          format: int32
          description: The ID of the workspace invoice preference which the project is associated with.
        workspace_resource_ids:
          type: array
          items:
            type: string
          description: '`workspace_resource_ids` will only be included in the response if `workspace_resources` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        workspace_resources_with_unnamed_ids:
          type: array
          items:
            type: string
          description: '`workspace_resources_with_unnamed_ids` will only be included in the response if `workspace_resources_with_unnamed` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
    UserFileAssociation:
      title: User File Association
      description: 'User File Associations act as a join object between a user, project, and

        an attachment (or Google document).'
      type: object
      properties:
        asset_object_ref:
          type: object
          description: '`asset_object_ref` will only be included in the response if `asset_object` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
          properties:
            key:
              type: string
            id:
              type: string
        post_id:
          type: string
          description: '`post_id` will only be included in the response if `post` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        workspace_id:
          type: string
          description: '`workspace_id` will only be included in the response if `workspace` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Post:
      title: Post
      description: A Post represents a message written by participants in a project that appears in the project.
      type: object
      properties:
        attachment_ids:
          type: array
          items:
            type: string
          description: '`attachment_ids` will only be included in the response if `attachments` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        created_at:
          type: string
          format: date-time
        external_reference_ids:
          type: array
          items:
            type: string
          description: '`external_reference_ids` will only be included in the response if `external_references` is in the list of included associations. See <a href=''#section/Includes''>include</a> section for usage.'
        formatted_message:
          type: string
          description: Sanitized HTML representation of the message with links, user m

# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mavenlink/refs/heads/main/openapi/mavenlink-user-file-associations-api-openapi.yml