/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Import Glossary

Import Glossary

Add or update glossary terms in bulk from a CSV file.

POST/v1/projects/{projectId}/glossary/importTry it
Session token

Import glossary terms from CSV. Send the CSV wrapped in JSON, or as a raw text/csv body. Terms the project already has are skipped by default, or overwritten in update mode. Rows that fail validation are reported and skipped; the rest are written in one transaction.

Note

Requires the admin or owner role, signed in with a session JWT — API keys are refused with 401. A member gets 403 forbidden with details.requiredRole: "admin" and details.currentRole — see Role errors. You must belong to the organization that owns {projectId}. Available on every plan.

CSV format

One term per row, in this column order. A header row is optional — it is detected when the first cell is term.

ColumnRequiredNotes
termyesUp to 200 characters. Matched exactly (case-sensitive) against existing terms
definitionnoUp to 2000 characters. Empty is allowed
preferred formnoUp to 200 characters
banned alternativesnoSeparated by ; or |. At most 20, each up to 100 characters
case-sensitivenoyes, true, 1 or y (any case) means yes; anything else means no

Standard CSV quoting is supported, including commas, doubled quotes and line breaks inside quoted fields. A leading byte-order mark is ignored. Blank lines are skipped.

Limits: at most 256 KB of CSV and 1000 data rows per request. A term that appears twice in the same file is imported once; the later row is reported as a duplicate.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID.

Query Parameters

NameDescription
mode:stringquery
Only for a raw text/csv body. skip leaves existing terms alone; update overwrites them with the row's values.
Default"skip"

Request Body

With Content-Type: application/json:

NameDescription
csv:stringbodyRequired
The CSV text.
mode:stringbody
skip or update, as above.
Default"skip"

With Content-Type: text/csv, the body is the CSV itself and mode comes from the query string.

Response — 200 OK

created, updated and skipped count the valid rows. invalid counts rows that were rejected, and errors gives the CSV line each one starts on and why. The import is recorded in the audit log as glossary.import.

Error Responses

400 Bad Request

validation_error — the JSON body has no csv string, or mode is not skip or update.

invalid_csv — no row could be imported. details.errors lists each rejected row:

json
{
"error": {
"code": "invalid_csv",
"message": "The CSV has no importable rows.",
"details": {
"errors": [
{ "line": 2, "message": "term is required" }
],
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

401 Unauthorized

No session JWT, an expired one, or an API key.

403 Forbidden

forbidden — your role is below admin (details.requiredRole, details.currentRole), or you are not a member of the organization that owns the project.

404 Not Found

not_found — the project does not exist or was deleted.

413 Payload Too Large

payload_too_large — the CSV is over 256 KB (details.bytes) or has more than 1000 data rows (details.rows). A request body far over the limit is refused before it is read, with details.maxBytes. Nothing is imported.

Was this page helpful? Yes No
Request
JSON bodyCSV bodyJavaScriptPythonGoRubyPHPJavaC#JSON body
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/glossary/import \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "Content-Type: application/json" \
-d '{
"csv": "term,definition,preferred form,banned alternatives,case-sensitive\nAPI key,A secret that authenticates a client,API key,api-key;apikey,no\nWebhook,An HTTP callback,,web hook,no",
"mode": "skip"
}'
Responseapplication/json
200OK
{
"data": {
"created": 12,
"updated": 0,
"skipped": 3,
"invalid": 1,
"errors": [
{ "line": 9, "message": "term is required" }
]
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext