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.
Column
Required
Notes
term
yes
Up to 200 characters. Matched exactly (case-sensitive) against existing terms
definition
no
Up to 2000 characters. Empty is allowed
preferred form
no
Up to 200 characters
banned alternatives
no
Separated by ; or |. At most 20, each up to 100 characters
case-sensitive
no
yes, 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.