Files.fm API

DVS tasks integration quickstart

Use this workflow to discover IDs and prepare a correct task request without guessing. DVS and DMS name the same public data-management API. The full DMS reference describes the actions and field types.

Prerequisites

Base URL: https://api.files.fm. Every DVS action uses POST JSON and includes user and user_access_token, except file attachments (section 4a), which use multipart/form-data with the same fields. A website session alone and an MCP Bearer token are not this authentication format. Never put credentials in URLs.

1. Discover fields and projects

POST /api_dvs/task/get_fields
Content-Type: application/json

{"user":"YOUR_USER","user_access_token":"YOUR_API_TOKEN"}

Read fields[].name, type, required, filter, options, section, and depends_on. Required task fields currently include name and dvs_project_id. Dropdown option IDs belong to this organization; example values from documentation are not reusable IDs.

The response also contains actions (actions this server supports for the section) and actor ({id, org_id} of the authenticated account). Check actions before relying on newer actions such as search_users or get_comments.

POST /api_dvs/project_2/get_documents
Content-Type: application/json

{"user":"YOUR_USER","user_access_token":"YOUR_API_TOKEN","limit":200,"offset":0}

Match the requested project against items[].name and retain its integer dvs_document_id. Continue with offset += items.length until offset >= total. Stop and ask for a choice if a name is absent or ambiguous. A short page is not itself the documented completion condition; use total.

Filters use field names with filter: true from get_fields. Unknown filter names are ignored, not rejected. Multiple values for a field are OR; different fields are AND. Lists omit HTML descriptions; use get_document for full content.

2. Discover assignable users and status options

POST /api_dvs/task/get_users
Content-Type: application/json

{"user":"YOUR_USER","user_access_token":"YOUR_API_TOKEN","dvs_project_id":123}

Here 123 represents the project ID just discovered. Resolve users[].display_name to an integer id; do not substitute email addresses or usernames in task user fields. Only use the users returned for that project — responsible and followers reject other IDs, including IDs found with search_users.

Resolve dropdown_status, dropdown_priority, and other dropdown values from the task field's options. For external followers, look up contact_person document IDs; those are different from platform user IDs. Contact and client relationships

3. Create a task

After discovery, construct this body using the real IDs and any additional required fields:

{
  "user": "YOUR_USER",
  "user_access_token": "YOUR_API_TOKEN",
  "create_params": {
    "dvs_project_id": 123,
    "name": "Review integration",
    "responsible": 456,
    "dropdown_status": 789,
    "description": "<p>Review the integration.</p>"
  }
}

Send to POST /api_dvs/task/create_document. Optional fields may be omitted. IDs 123, 456, and 789 above are illustrative; replace them with discovery results.

{"dvs_document_id":4822}

Retain the returned task ID. Creation and updates can send notifications. Task create, update and comment actions accept an optional idempotency_key; uploads do not. With a key, retry the exact same request using the same key. After a timeout or uncertain write outcome, reconcile with task reads/comments before retrying. Requests without a key retain legacy behavior and have no deduplication guarantee; model hooks may still leave partial state, so a failure is not proof that nothing was saved.

3a. Inspect a person's task queue

  1. Status ID: from task/get_fields, pick the wanted entry of the dropdown_status field's options by display_name and keep its id.
  2. User ID: for your own queue use actor.id from get_fields. For someone else, search the organization by name:
POST /api_dvs/task/search_users
Content-Type: application/json

{"user":"YOUR_USER","user_access_token":"YOUR_API_TOKEN","pattern":"anna smith","limit":5}

search_users returns up to limit (max 20) active organization users as {id, display_name, has_access}; refine the pattern if the person is not in the result or if several people match. task/get_users for a known project is an alternative, but it lists only users assignable in that project.

  1. List the queue; both filters are applied on the server (different fields are AND, several values of one field are OR):
POST /api_dvs/task/get_documents
Content-Type: application/json

{"user":"YOUR_USER","user_access_token":"YOUR_API_TOKEN","filters":{"responsible":456,"dropdown_status":[789,790]},"order":"oldest","limit":20}

responsible matches the task's responsible person only, not followers. Use task/get_comments to read and paginate a task's comment history, including author organization and activity.

4. Read, update, and comment

Call task/get_document with auth and dvs_document_id to read the full saved record. IDs in read responses are often objects such as { "id": 456, "display_name": "..." }; write requests need the scalar IDs.

{
  "user": "YOUR_USER",
  "user_access_token": "YOUR_API_TOKEN",
  "dvs_document_id": 4822,
  "update_params": { "dropdown_status": 790 }
}

Send to POST /api_dvs/task/update_document. Discover 790 from get_fields. This is a partial update: omitted fields keep their values; arrays supplied for workers/relations replace that field's selection. The task's project cannot be changed through this API.

{
  "user": "YOUR_USER",
  "user_access_token": "YOUR_API_TOKEN",
  "dvs_document_id": 4822,
  "comment": "Integration reviewed."
}

Send to POST /api_dvs/task/add_comment. Mention a platform user with @[USER:456]; mentions can notify users. There is no documented task delete action in this API. Clean up test records through the authorized DVS UI.

4a. Attach a file

When get_fields lists upload_document_file in actions, attach one file per request as multipart/form-data:

curl -X POST 'https://api.files.fm/api_dvs/task/upload_document_file' \
  -F user=YOUR_USER -F user_access_token=YOUR_API_TOKEN \
  -F dvs_document_id=789 -F file=@report.pdf

The response contains file_hash and upload_hash (the task's attachment folder, created on first use). If the response has "success": false instead, the file was not saved; read error_message. A file whose name already exists is saved with a numbered name, for example report (1).pdf. To list a task's files, read upload_hash from get_document and call POST /api_v2/get_folder_content with folder_hash. See upload_document_file.

curl

Set credentials in your local environment. The following uses Node to write JSON to stdin, keeping the token out of the URL and curl arguments:

export FILESFM_USER='YOUR_USER'
export FILESFM_API_TOKEN='YOUR_API_TOKEN'
node -e 'process.stdout.write(JSON.stringify({user:process.env.FILESFM_USER,user_access_token:process.env.FILESFM_API_TOKEN}))' |
  curl --silent --show-error --fail-with-body --max-time 30 \
    'https://api.files.fm/api_dvs/task/get_fields' \
    -H 'Content-Type: application/json' --data-binary @-

For write calls, prepare the JSON body from discovered IDs in a local private file and use --data-binary @request.json. Protect and remove credential-bearing files after use. Do not use verbose HTTP traces with real credentials.

JavaScript (Node 18+ or a trusted server)

async function dvs(section, action, params = {}) {
  const response = await fetch(`https://api.files.fm/api_dvs/${section}/${action}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ...params, user: process.env.FILESFM_USER,
      user_access_token: process.env.FILESFM_API_TOKEN }),
    signal: AbortSignal.timeout(30000)
  });
  const text = await response.text();
  if (!response.ok) throw new Error(`DVS HTTP ${response.status}`);
  if (!text) throw new Error('Missing success response');
  return JSON.parse(text);
}

const { fields } = await dvs('task', 'get_fields');
const projects = [];
let offset = 0;
while (true) {
  const page = await dvs('project_2', 'get_documents', { limit: 200, offset });
  projects.push(...page.items);
  offset += page.items.length;
  if (offset >= page.total) break;
  if (!page.items.length) throw new Error('Incomplete project listing');
}
const matches = projects.filter(p => p.name === process.env.FILESFM_PROJECT_NAME);
if (matches.length !== 1) throw new Error('Choose one existing project');
const projectId = matches[0].dvs_document_id;
const { users } = await dvs('task', 'get_users', { dvs_project_id: projectId });
const statusOptions = fields.find(f => f.name === 'dropdown_status')?.options || [];
// Select a user and status from users/statusOptions; omit them if not needed.
const createParams = { dvs_project_id: projectId, name: 'Review integration' };
console.log({ endpoint: '/api_dvs/task/create_document', create_params: createParams });

// Only run the following block when task creation and notifications are authorized:
// const created = await dvs('task', 'create_document', { create_params: createParams });
// const task = await dvs('task', 'get_document', { dvs_document_id: created.dvs_document_id });
// await dvs('task', 'update_document', { dvs_document_id: task.dvs_document_id,
//   update_params: { description: '<p>Integration verified.</p>' } });
// await dvs('task', 'add_comment', { dvs_document_id: task.dvs_document_id,
//   comment: 'Integration reviewed.' });

Keep API tokens on a trusted server, not in shipped browser JavaScript. Client-side UI should call your own authorized integration backend.

PHP 7.4+

<?php
function dvs($section, $action, array $params = []) {
    $params['user'] = getenv('FILESFM_USER');
    $params['user_access_token'] = getenv('FILESFM_API_TOKEN');
    $curl = curl_init('https://api.files.fm/api_dvs/' . $section . '/' . $action);
    curl_setopt_array($curl, [
        CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode($params, JSON_THROW_ON_ERROR),
        CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 30,
    ]);
    $body = curl_exec($curl);
    $status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    $failed = $body === false;
    curl_close($curl);
    if ($failed) { throw new RuntimeException('DVS transport failed'); }
    if ($status !== 200) { throw new RuntimeException('DVS HTTP ' . $status); }
    return json_decode($body, true, 512, JSON_THROW_ON_ERROR);
}

$fields = dvs('task', 'get_fields')['fields'];
$projects = []; $offset = 0;
do {
    $page = dvs('project_2', 'get_documents', ['limit' => 200, 'offset' => $offset]);
    $projects = array_merge($projects, $page['items']);
    $offset += count($page['items']);
    if (!$page['items'] && $offset < $page['total']) {
        throw new RuntimeException('Incomplete project listing');
    }
} while ($offset < $page['total']);
$matches = array_values(array_filter($projects, function ($p) {
    return $p['name'] === getenv('FILESFM_PROJECT_NAME');
}));
if (count($matches) !== 1) { throw new RuntimeException('Choose one existing project'); }
$projectId = $matches[0]['dvs_document_id'];
$users = dvs('task', 'get_users', ['dvs_project_id' => $projectId])['users'];
$createParams = ['dvs_project_id' => $projectId, 'name' => 'Review integration'];
// After explicit write authorization:
// $created = dvs('task', 'create_document', ['create_params' => $createParams]);
// $task = dvs('task', 'get_document', ['dvs_document_id' => $created['dvs_document_id']]);
// dvs('task', 'update_document', ['dvs_document_id' => $task['dvs_document_id'],
//     'update_params' => ['description' => '<p>Integration verified.</p>']]);
// dvs('task', 'add_comment', ['dvs_document_id' => $task['dvs_document_id'],
//     'comment' => 'Integration reviewed.']);

Failure handling and MCP

DVS errors can have an empty body. Check status first: 400 parameters, 401 authentication or missing session organization, 405 method/section/permission/not-found conditions, 500 backend failure. Do not log request bodies containing tokens. No universal public DVS request quota is promised; infrastructure can enforce additional limits.

Public MCP filesfm_search_docs and filesfm_get_doc can find and retrieve this guide without auth. Where enabled, the MCP DVS tools also read and change supported registers, add section-aware comments, manage project members with separate consent, and attach files to tasks with the user's own permissions and discovered IDs.