Access & visibility
Allow documents.ListTextDocumentShares on your API key.
Acting member required. Send Brigg-Act-As with an approved member account ID. The key supplies permissions; the member selects whose data is used.
The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply.
Request fields
Send a JSON object with the following fields. Required fields must be included; omit optional fields you do not need.
file_idstringRequiredUse the file_id of a collaborative text document. Find an existing document with ListDocuments and select kind=text_document. An uploaded PDF, Word file or plain-text file is not a collaborative text document. documents.CreateTextDocument.
At least 1 character.
Response
Returns 200 OK with a JSON body.
This operation has no continuation cursor. An empty items array means no matching visible results were returned.
An empty items array means no active links remain. Each URL still grants access to the current content; this response contains bearer links and should not be logged.
itemsarray of Document share linkRequiredActive, unexpired share links for this text document, newest first. Revoked and expired links are excluded. This operation has no cursor pagination.
Item fields
urlstringRequiredBearer link that grants access to this document. Treat it as a secret and share it only with intended readers.
created_bystring or nullRequiredAccount ID of the person who created this link.
created_atnumberRequiredShare-link creation time in Unix milliseconds.
expires_atnumberRequiredExpiry time in Unix milliseconds. Access through this link stops after this time.
access_countnumberRequiredNumber of recorded accesses through this share link.
last_accessed_atnumber or nullRequiredMost recent access time in Unix milliseconds, or null if the link has not been used.
Errors & retries
This operation reads data. It needs no idempotency key and can be retried after a transient failure.
For rate limits, follow the server’s retry guidance and back off. See HTTP errors and safe retries and limits.
| HTTP status | Code | What to do |
|---|---|---|
| 400 | invalid_json |
Send a JSON object with Content-Type: application/json. |
| 400 | invalid_input |
Check the request fields and types. |
| 401 | invalid_key |
The workspace API key is missing, invalid or revoked. |
| 403 | forbidden |
Check the key’s operation and resource grants. Supply Brigg-Act-As with a member authorized by the key’s delegation grant. The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply. |
| 404 | not_found |
The requested operation or resource is not available to this credential. |
| 429 | rate_limited |
Wait for Retry-After before retrying. |
| 409 | not_text_document |
This file is not a collaborative text document. Use CreateTextDocument or select kind=text_document from ListDocuments. |
Next steps
JSON schemas
Use the complete schemas for validation or client generation.
Full request JSON schema
{
"type": "object",
"properties": {
"file_id": {
"type": "string",
"minLength": 1,
"description": "Use the file_id of a collaborative text document. Find an existing document with [ListDocuments](/reference/documents/ListDocuments) and select kind=text_document. An uploaded PDF, Word file or plain-text file is not a collaborative text document. [documents.CreateTextDocument](/reference/documents/CreateTextDocument)."
}
},
"required": [
"file_id"
],
"additionalProperties": false,
"examples": [
{
"file_id": "f_project_notes"
}
]
}Full response JSON schema
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"share_id": {
"type": "string",
"description": "Non-secret identifier of a share link returned by a share or share-list operation. Use it to revoke that link; it cannot be used to open the document. Treat the separate url value as a bearer credential.",
"examples": [
"share_proposal"
]
},
"url": {
"type": "string",
"description": "Bearer link that grants access to this document. Treat it as a secret and share it only with intended readers.",
"examples": [
"https://example.com/share/proposal"
]
},
"created_by": {
"type": [
"string",
"null"
],
"description": "Account ID of the person who created this link.",
"examples": [
"account_alex"
]
},
"created_at": {
"type": "number",
"description": "Share-link creation time in Unix milliseconds."
},
"expires_at": {
"type": "number",
"description": "Expiry time in Unix milliseconds. Access through this link stops after this time.",
"examples": [
1794906000000
]
},
"access_count": {
"type": "number",
"description": "Number of recorded accesses through this share link.",
"examples": [
0
]
},
"last_accessed_at": {
"type": [
"number",
"null"
],
"description": "Most recent access time in Unix milliseconds, or null if the link has not been used.",
"examples": [
null
]
}
},
"required": [
"share_id",
"url",
"created_by",
"created_at",
"expires_at",
"access_count",
"last_accessed_at"
],
"additionalProperties": false,
"title": "Document share link"
},
"description": "Active, unexpired share links for this text document, newest first. Revoked and expired links are excluded. This operation has no cursor pagination."
}
},
"required": [
"items"
],
"additionalProperties": false,
"examples": [
{
"items": [
{
"share_id": "share_project_notes",
"url": "https://app.example.com/share/fictional-link?org=o_northstar",
"expires_at": 1794906000000,
"created_by": "a_jamie",
"created_at": 1794301200000,
"access_count": 2,
"last_accessed_at": 1794387600000
}
]
}
]
}