Generate File Description
curl --request POST \
--url https://api.example.com/files/{file_id}/generate-description \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/files/{file_id}/generate-description"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/files/{file_id}/generate-description', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/files/{file_id}/generate-description",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/files/{file_id}/generate-description"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/files/{file_id}/generate-description")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/files/{file_id}/generate-description")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Files
Generate an AI Description
Generate an AI one-liner description for a file and persist it.
Uses the filename as the primary signal. If the filename is generic or short (≤ 8 chars stem, or matches common placeholder patterns), downloads the file from S3 and extracts text (PDF via pypdf, plain-text verbatim) to give the LLM richer context.
POST
/
files
/
{file_id}
/
generate-description
Generate File Description
curl --request POST \
--url https://api.example.com/files/{file_id}/generate-description \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/files/{file_id}/generate-description"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/files/{file_id}/generate-description', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/files/{file_id}/generate-description",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/files/{file_id}/generate-description"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/files/{file_id}/generate-description")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/files/{file_id}/generate-description")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Generates a one-line description and persists it to
This response does not include the rest of the file row — re-fetch via List Files if you need it.
description. Uses the filename as the primary signal; if the filename looks generic or is too short (an 8-character-or-shorter stem, or matches patterns like document, scan, untitled, copy, temp), it also downloads the object from S3 and extracts a text preview (PDF via pypdf, plain text verbatim, both capped) to give the model more context. Requires AI to be configured on this deployment.
The saved description is the only thing this call caches back to the files row — there’s no stored “extracted text” field otherwise; the S3 read that feeds this happens live, on demand.
Auth
Requires a CRM manage scope and an active organization on the token. Any*:manage scope qualifies — in practice contacts:manage, deals:manage, companies:manage, or activities:manage.
Response
| Field | Type | Description |
|---|---|---|
description | string | The generated (and already-saved) description. |
Errors
| Status | Cause |
|---|---|
404 Not Found | File doesn’t exist (or isn’t in this org, or is archived). |
503 Service Unavailable | AI isn’t configured on this deployment. |
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
UUID of the file to generate an AI description for.
Response
Successful Response
The response is of type Response Generate File Description Files File Id Generate Description Post · object.