For AI agents: markdown of this page — /docs-content-en/note/files/get.md documentation index — /llms.txt

Get file metadata

GET /v1/note/documents/:documentId/files/:id

Returns the file metadata and a ready-made markup snippet for inserting the attachment into the document content. Available to a read-only key as well.

Parameters

Parameter Type Required Description
ParameterdocumentId (path) Typeinteger Requiredyes DescriptionDocument the file is attached to. Get the identifier from POST /v1/note/documents
Parameterid (path) Typeinteger Requiredyes DescriptionFile identifier. Returned from POST /v1/note/documents/:documentId/files

Examples

curl — personal key

Terminal 
curl https://vibecode.bitrix24.com/v1/note/documents/77/files/5001 \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/note/documents/77/files/5001 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/note/documents/77/files/5001', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log(data.assetMarkdown)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/note/documents/77/files/5001', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typenumber DescriptionFile identifier
Fielddata.documentId Typenumber DescriptionDocument the file is attached to
Fielddata.name Typestring DescriptionOriginal file name
Fielddata.size Typenumber DescriptionFile size in bytes
Fielddata.mimeType Typestring DescriptionFile content type in MIME format, determined at save time
Fielddata.assetType Typestring DescriptionAttachment category: image, video, or file
Fielddata.assetMarkdown Typestring DescriptionReady-made [[<assetType> fileId=<id>]] snippet for inserting into the content

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 5001,
    "documentId": 77,
    "name": "diagram.png",
    "size": 6321,
    "mimeType": "image/png",
    "assetType": "image",
    "assetMarkdown": "[[image fileId=5001]]"
  }
}

Error response example

404 — document or file not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Record with ID = `999999` not found"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptiondocumentId or id is missing, or a parameter has the wrong type
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the note scope
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe document or file does not exist, there is no access, or the file is not attached to the document
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens

Full list of common API errors — Errors.

Known specifics

assetMarkdown format and inserting the attachment. To make the attachment appear in the document, add assetMarkdown as a separate line in markdown and call PATCH /v1/note/documents/:id. The snippet must start at the beginning of a line, with no other characters on that same line. The type is written in lowercase, and fileId is a positive integer.

See also