Document Management API
The Document Management API allows you to create and manage documents (and proposals) in your TaskIP workspace. You can list, create, archive and share documents, edit their content blocks, publish them to a public link, and export them as PDF.
Endpoints Overview
There is no update endpoint. PUT /documents/{uuid} is not available. To change a document use the specific endpoints above (rename, move to folder, save blocks, share, publish, cover).
Authentication and Common Behavior
Every request must send the secret key header:
X-Secret-Key: your-secret-key-here
Content-Type: application/json- Documents are identified by their
uuid(string), not the numericid. - The workspace must have the Public API module enabled and plan access, otherwise the request is rejected before reaching the endpoint.
- Requests act as the user linked to the secret key. A document that user cannot access returns an error (see Error Responses), and document-level rules (for example, only the owner can share) apply.
Access Type Values
Used by access_type in the share and invite endpoints, and returned in permissions[].access_type.
| Value | Meaning |
|---|---|
1 | Full access |
2 | Can edit |
3 | View only |
4 | Comment only |
Visibility Values
| Value | Label |
|---|---|
0 | Private |
1 | Public |
2 | Team Only |
Get All Documents
Retrieve a paginated list of documents visible to the user that owns the secret key. Results are ordered newest first (id descending).
GET /api/public-v1/documentsQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
item | integer | No | Items per page (default: 10). Use 0 to return all documents without pagination |
page | integer | No | Page number |
search | string | No | Search by document name |
visibility | integer | No | Filter by visibility. Only 0 and 1 are applied as filters; other values are ignored |
status | integer | No | 1 = only published (shared) documents, 0 = only unpublished documents |
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/documents?item=20&search=proposal" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json"Example Response
{
"data": [
{
"id": 1,
"uuid": "abc123def456",
"created_by": {
"id": 3,
"name": "Sarah Johnson",
"image": null,
"type": "user",
"email": "sarah@company.com",
"contact_id": null
},
"folder": {
"id": 5,
"uuid": "folder-uuid",
"name": "Proposals"
},
"name": "Project Proposal - Acme Corp",
"visibility": {
"id": 2,
"label": "Team Only"
},
"permissions": [
{
"id": 1,
"document_id": 1,
"user_id": 8,
"access_type": 2,
"user": {
"name": "David Chen",
"image": null,
"type": "user",
"email": "david@company.com",
"contact_id": null
}
}
],
"created_at": "Jan 15, 2024, 09:30 AM",
"access": "full",
"publish": null,
"teams": [],
"type": 1,
"type_label": "Document",
"is_signable": true,
"is_self_signable": false,
"send_in_order": false,
"is_editable": true,
"template_type": 1,
"status": 1,
"status_label": "Draft",
"expired_at": "Jan 30, 2024",
"signers": []
}
],
"links": {
"first": "https://public-api.taskip.net/api/public-v1/documents?page=1",
"last": "https://public-api.taskip.net/api/public-v1/documents?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://public-api.taskip.net/api/public-v1/documents",
"per_page": 10,
"to": 1,
"total": 1
}
}Response Field Notes
| Field | Description |
|---|---|
access | Your access level on the document: full, edit, view, comment or none |
publish | Public URL if the document is published, otherwise null |
type / type_label | 1 = Document, 2 = Proposal |
template_type | 1 = Prebuilt template, 2 = Custom template, 3 = PDF upload |
status / status_label | 1 = Draft, 2 = In Progress, 3 = Completed |
signers | Signers attached to the document (for signable documents) |
Create a Document
Create a new document.
POST /api/public-v1/documentsRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Document name (max 191 characters) |
visibility | integer | Yes | 0 = Private, 1 = Public, 2 = Team Only |
type | integer | No | 1 = Document (default), 2 = Proposal |
is_signable | boolean | No | Whether the document can be signed (default: true) |
is_self_signable | boolean | No | Whether the owner can self-sign (default: false) |
template_type | integer | No | 1 = Prebuilt (default), 2 = Custom, 3 = PDF upload |
status | integer | No | 1 = Draft (default), 2 = In Progress |
media | integer | No | ID of an uploaded media file (for example a PDF) to attach |
The service also reads the following optional fields. They are not validated by the request class, so malformed values may produce a server error:
| Field | Type | Description |
|---|---|---|
expired_at | datetime string | Expiry date (default: 15 days from now) |
send_in_order | boolean | Signers must sign in order (default: false) |
template_id | string | Template name used to prefill the document blocks |
teams | array | Team IDs to attach to the document |
signers | array | Signer objects. Each uses email (required), order (required), name, contact_id, type, status |
folder_id is not accepted when creating a document (it is not saved). Use Move a Document to a Folder afterwards.
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/documents" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"name": "Project Requirements - TechCorp",
"visibility": 2
}'JavaScript Example
const response = await fetch('https://public-api.taskip.net/api/public-v1/documents', {
method: 'POST',
headers: {
'X-Secret-Key': 'your-secret-key-here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Project Requirements - TechCorp',
visibility: 2
})
});
const result = await response.json();Example Response
{
"status": 200,
"msg": "Document Created Successfully",
"document": {
"id": 126,
"uuid": "mno345pqr678",
"created_by": {
"id": 3,
"name": "Current User",
"image": null,
"type": "user",
"email": "current@company.com",
"contact_id": null
},
"folder": { "id": null, "uuid": null, "name": null },
"name": "Project Requirements - TechCorp",
"visibility": { "id": 2, "label": "Team Only" },
"permissions": [],
"created_at": "Jan 20, 2024, 10:30 AM",
"access": "full",
"publish": null,
"teams": [],
"type": 1,
"type_label": "Document",
"is_signable": true,
"is_self_signable": false,
"send_in_order": false,
"is_editable": true,
"template_type": 1,
"status": 1,
"status_label": "Draft",
"expired_at": "Feb 04, 2024",
"signers": []
}
}Errors
- Validation failure:
422with{"error": {"name": ["The name field is required."]}}. - Plan document limit reached:
422with{"error": {"msg": ["You have reached maximum number of documents limits, upgrade your plan to create more documents"]}}.
Get a Specific Document
Retrieve a document including its content blocks.
GET /api/public-v1/documents/{uuid}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
uuid | string | Yes | Document UUID |
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/documents/abc123def456" \
-H "X-Secret-Key: your-secret-key-here"Example Response
{
"id": 126,
"name": "Project Requirements - TechCorp",
"uuid": "abc123def456",
"type": 1,
"is_signable": true,
"is_self_signable": false,
"send_in_order": false,
"is_editable": true,
"is_email_sent": false,
"template_type": 1,
"updated_at": "Jan 20, 2024, 10:30 AM",
"cover": null,
"cover_position": null,
"signers": [],
"media": null,
"signatures": [],
"thumbnail": null,
"blocks": {
"data": [
{
"id": "block-uuid-1",
"type": "paragraph",
"props": {},
"content": [],
"children": []
}
]
},
"permissions": [],
"access": "full",
"publish": null,
"mentions": [
{ "email": "david@company.com", "name": "David Chen" }
],
"teams": []
}Errors
404{"status": 404, "msg": "Document not found"}422{"error": {"msg": ["You don't have permission to access this document"]}}
Delete a Document
Archive a document. The document is soft-deleted (the API responds that it was archived).
DELETE /api/public-v1/documents/{uuid}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
uuid | string | Yes | Document UUID |
Example Request
curl -X DELETE "https://public-api.taskip.net/api/public-v1/documents/abc123def456" \
-H "X-Secret-Key: your-secret-key-here"Example Response
{
"msg": "Document archived successfully",
"status": 200
}Errors
404{"status": 404, "msg": "Document not found"}422{"error": {"msg": ["You don't have permission to delete document"]}}
Save Document Blocks
Save the content of a document. The submitted list replaces the document’s blocks: existing blocks whose id is not in the request are deleted, blocks with a matching id are updated, and new ones are created. The array order becomes the block order.
POST /api/public-v1/documents/blocks/store/{uuid}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
uuid | string | Yes | Document UUID |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
blocks | array | Yes | Ordered list of block objects |
blocks[].id | string | Yes | Block UUID (client generated) |
blocks[].type | string | Yes | Block type (for example paragraph, heading, table) |
blocks[].props | object | Yes | Block properties |
blocks[].content | array | No | Block content |
blocks[].children | array | Yes | Nested child blocks (use [] when none) |
These fields are not checked by a request validator. Omitting blocks, or id, type, props or children on a block, results in a server error instead of a 422.
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/documents/blocks/store/abc123def456" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"blocks": [
{
"id": "block-uuid-1",
"type": "paragraph",
"props": {},
"content": [{ "type": "text", "text": "Hello world", "styles": {} }],
"children": []
}
]
}'Example Response
{
"msg": "document updated",
"updatedAt": "1 second ago"
}Errors
404{"status": 404, "msg": "Document not found"}422{"error": {"msg": ["You don't have permission to update a document"]}}
Rename a Document
POST /api/public-v1/documents/blocks/rename/{uuid}Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | New name (max 191 characters) |
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/documents/blocks/rename/abc123def456" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{ "name": "Project Requirements v2" }'Example Response
{
"msg": "Document Renamed successfully",
"status": 200
}Errors
422{"error": {"msg": ["name field is required"]}}whennameis missing, not a string, or longer than 191 characters404{"status": 404, "msg": "Document not found"}422{"error": {"msg": ["You don't have permission to rename a document"]}}
Move a Document to a Folder
POST /api/public-v1/documents/blocks/move-to-folder/{uuid}Request Body
| Field | Type | Required | Description |
|---|---|---|---|
folder_id | string | Yes | ID of the destination folder. The value is stored as given and is not checked for existence |
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/documents/blocks/move-to-folder/abc123def456" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{ "folder_id": "5" }'Example Response
{
"msg": "Document Moved successfully",
"status": 200
}Errors
422{"error": {"msg": ["select a folder"]}}whenfolder_idis missing404{"status": 404, "msg": "Document not found"}422{"error": {"msg": ["You don't have permission to move to folder"]}}
Share a Document with a User
Give a user access to a document, change their access level, or remove their access. Only the document owner (the creator) can share it.
POST /api/public-v1/documents/blocks/share/{uuid}Request Body
| Field | Type | Required | Description |
|---|---|---|---|
user_id | integer | Yes | ID of the user |
access_type | integer | Yes (unless removing) | 1 full, 2 edit, 3 view, 4 comment (see Access Type Values). An invalid value returns 422 |
action | string | No | Send remove to revoke the user’s access |
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/documents/blocks/share/abc123def456" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{ "user_id": 8, "access_type": 2 }'Example Responses
{ "status": 200, "msg": "Document Shared Successfully" }{ "status": 200, "msg": "Document Shared Removed" }Errors
404{"status": 404, "msg": "Document not found or you are not owner of this document"}422{"status": 422, "msg": "Invalid access type"}whenaccess_typeis not a valid access type value422{"error": {"msg": ["You don't have permission to share document"]}}
Duplicate a Document
Create a copy of a document (name gets a copy suffix) including its blocks. The new document gets its own share row; the original document’s sharing/publish state is not changed.
POST /api/public-v1/documents/blocks/duplicate_document/{uuid}No request body is required.
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/documents/blocks/duplicate_document/abc123def456" \
-H "X-Secret-Key: your-secret-key-here"Example Response
{
"msg": "Document Duplicate successfully",
"status": 200
}The response does not include the new document’s UUID. Call Get All Documents to find it.
Errors
404{"status": 404, "msg": "Document not found"}422{"error": {"msg": ["You don't have permission to duplicate document"]}}422plan document limit reached (same message as in Create a Document)
Download Document as PDF
Generate and return the document as an A4 PDF. Note this is a POST request.
POST /api/public-v1/documents/download/{uuid}Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/documents/download/abc123def456" \
-H "X-Secret-Key: your-secret-key-here" \
-o document.pdfJavaScript Example (with Blob)
const response = await fetch('https://public-api.taskip.net/api/public-v1/documents/download/abc123def456', {
method: 'POST',
headers: { 'X-Secret-Key': 'your-secret-key-here' }
});
if (response.ok) {
const blob = await response.blob();
const url = window.URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'document.pdf';
document.body.appendChild(a);
a.click();
window.URL.revokeObjectURL(url);
}Response
The response body is the PDF file (Content-Type: application/pdf) rendered from the document’s blocks. The file name and PDF title use the document name, followed by the date (<document name>-<dd-mm-yy>.pdf).
For an unknown uuid the API returns 422 with {"error": {"msg": ["Document not found"]}}.
Invite or Revoke Access
Invite a team member, a client contact or a whole team to a document, change their access level, or revoke access.
POST /api/public-v1/documents-invite/{uuid}Request Body
| Field | Type | Required | Description |
|---|---|---|---|
invitationType | integer | Yes | 1 = Team member, 2 = Contact, 3 = Team |
invitationTypeId | integer | Yes | ID of the team member’s user, the contact’s user, or the team (depending on invitationType) |
actionType | integer | Yes | 0 = invite / update access, 1 = revoke access. Send a JSON integer |
access_type | integer | No | 1 full, 2 edit, 3 view, 4 comment. Not validated; required in practice when inviting |
For contacts (invitationType: 2) the contact must have client portal access enabled.
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/documents-invite/abc123def456" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"invitationType": 1,
"invitationTypeId": 8,
"actionType": 0,
"access_type": 3
}'Example Responses
New invitation (a notification is sent to the user, or to each team member):
{
"msg": "Invitation send successfully",
"contact": {
"id": 4,
"document_id": 126,
"user_id": 8,
"access_type": 3,
"user": {
"name": "David Chen",
"image": null,
"type": "user",
"email": "david@company.com",
"contact_id": null
}
}
}For invitationType: 3 the object is returned under team instead of contact. When the user/team already had access, msg is Access Type Changed successfully. When revoking, the response is {"msg": "User access revoke from document"} (or {"msg": "Team access revoked from the document"} for teams).
Errors
Validation errors return 422 with {"error": {...}}. Other 422 errors use {"error": {"msg": [...]}}:
Document not foundYou don't have permission to invite anyone to this documentUser not foundThis contact does not have portal access and cannot be shared with
Publish or Unpublish a Document
Publish a document to a public link, or remove the public link.
POST /api/public-v1/documents-publish/{uuid}Request Body
| Field | Type | Required | Description |
|---|---|---|---|
actionType | integer | Yes | 0 = publish, 1 = unpublish |
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/documents-publish/abc123def456" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{ "actionType": 0 }'Example Responses
{ "msg": "Document publish successfully", "slug": "project-requirements-techcorp-abc123def456" }If already published: {"msg": "Document already published", "slug": "..."}. After unpublishing: {"msg": "Document unpublished", "slug": null}.
A document.published webhook event is fired for matching active webhooks when a document is published.
Errors
422{"error": {"actionType": ["The action type field is required."]}}(validation)422{"error": {"msg": ["Document not found"]}}422{"error": {"msg": ["You don't have permission to publish this document"]}}
Update Thumbnail
POST /api/public-v1/documents-thumbnail/{uuid}Set the document’s thumbnail to an emoji or an uploaded image.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
type | integer | Yes | 0 = emoji, 1 = uploaded image |
emoji | string | Required if type is 0 | Emoji character |
media_id | integer | Required if type is 1 | ID of an uploaded media file |
When type is 1, any previous thumbnail image is replaced by the new media file.
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/documents-thumbnail/abc123def456" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{ "type": 0, "emoji": "📄" }'Example Response
{
"data": { "type": 0, "emoji": "📄", "media": null },
"msg": "Thumbnail Updated"
}For type 1, media holds the uploaded file (id, title, ext, size, url, media_type, createdAt).
Errors
422{"error": {"type": ["The type field is required."]}}(validation;emoji/media_idare required for the matchingtype)422{"error": {"msg": ["Document not found"]}}422{"error": {"msg": ["You don't have permission to change thumbnail of this document"]}}(requires an admin or full access)
Update Cover Photo
Set or replace the document’s cover photo.
POST /api/public-v1/documents-cover/{uuid}Request Body
| Field | Type | Required | Description |
|---|---|---|---|
type | integer | Yes | 0 = import from an image URL, 1 = use an already uploaded media file |
image_url | string | Required if type is 0 | Image URL to import |
media_id | integer | Required if type is 1 | ID of an uploaded media file |
Any existing cover photo is replaced. With type 0, if the image cannot be downloaded from image_url, the cover is left unchanged and the response still reports success.
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/documents-cover/abc123def456" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{ "type": 1, "media_id": 87 }'Example Response
{
"data": {
"id": 87,
"title": "cover.jpg",
"ext": "jpg",
"size": 120345,
"url": "https://.../cover.jpg",
"media_type": "image",
"createdAt": "26-01-2024 02:30:00"
},
"msg": "Cover Updated"
}data is null if no cover photo is set after the call (for example when the media_id does not exist).
Errors
422{"error": {"type": ["The type field is required."]}}(validation)422{"error": {"msg": ["Document not found"]}}422{"error": {"msg": ["You don't have permission to change cover of this document"]}}(requires an admin or full access)
Mention a User
Send a mention notification to a user about a document.
POST /api/public-v1/documents/mention/userRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name of the mentioned user |
document_uuid | string | Yes | UUID of the document |
email | string | Yes | Email of the mentioned user (must be an existing user in the workspace) |
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/documents/mention/user" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"name": "David Chen",
"document_uuid": "abc123def456",
"email": "david@company.com"
}'Example Response
"ok"Errors
422{"error": {"email": ["The email field is required."]}}(validation)422{"error": {"msg": ["user not found"]}}when no user has that email
Error Responses
| Status Code | Description |
|---|---|
401 | {"message": "Secret keys are missing."} - no X-Secret-Key header |
404 | {"status": 404, "msg": "Workspace not found"} - unknown or expired secret key; or {"status": 404, "msg": "Document not found"} |
422 | Validation errors ({"error": {"field": ["..."]}}) and permission/business-rule errors ({"error": {"msg": ["..."]}}) |
503 | Workspace is in read-only maintenance and the request is a write |
Document Object
| Field | Type | Description |
|---|---|---|
id | integer | Document ID |
uuid | string | Document UUID used in URLs |
created_by | object | Owner (id, name, image, type, email, contact_id) |
folder | object | id, uuid, name (all null when not in a folder) |
name | string | Document name |
visibility | object | id (0/1/2) and label |
permissions | array | Users with access (user_id, access_type, user), including members of attached teams |
created_at | string | Formatted date (for example Jan 15, 2024, 09:30 AM) |
access | string | Current user’s access: full, edit, view, comment, none |
publish | string|null | Public URL when published |
teams | array | Attached teams with id, name, access_type, members |
type, type_label | integer, string | Document (1) or Proposal (2) |
is_signable, is_self_signable, send_in_order, is_editable | boolean | Signing and editing flags |
template_type | integer | 1, 2 or 3 |
status, status_label | integer, string | Draft (1), In Progress (2), Completed (3) |
expired_at | string | Expiry date (for example Jan 30, 2024) |
signers | array | Signers |