Skip to Content
Document Management API

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

MethodEndpointDescription
GET/api/public-v1/documentsGet all documents
POST/api/public-v1/documentsCreate a document
GET/api/public-v1/documents/{uuid}Get a document with its blocks
DELETE/api/public-v1/documents/{uuid}Archive (delete) a document
POST/api/public-v1/documents/blocks/store/{uuid}Save the content blocks of a document
POST/api/public-v1/documents/blocks/rename/{uuid}Rename a document
POST/api/public-v1/documents/blocks/move-to-folder/{uuid}Move a document to a folder
POST/api/public-v1/documents/blocks/share/{uuid}Share a document with a user (or remove access)
POST/api/public-v1/documents/blocks/duplicate_document/{uuid}Duplicate a document
POST/api/public-v1/documents/download/{uuid}Download a document as PDF
POST/api/public-v1/documents-invite/{uuid}Invite a team member, contact or team (or revoke access)
POST/api/public-v1/documents-publish/{uuid}Publish or unpublish a document
POST/api/public-v1/documents-thumbnail/{uuid}Update the thumbnail
POST/api/public-v1/documents-cover/{uuid}Update the cover photo
POST/api/public-v1/documents/mention/userNotify a user that they were mentioned
⚠️

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 numeric id.
  • 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.

ValueMeaning
1Full access
2Can edit
3View only
4Comment only

Visibility Values

ValueLabel
0Private
1Public
2Team 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/documents

Query Parameters

ParameterTypeRequiredDescription
itemintegerNoItems per page (default: 10). Use 0 to return all documents without pagination
pageintegerNoPage number
searchstringNoSearch by document name
visibilityintegerNoFilter by visibility. Only 0 and 1 are applied as filters; other values are ignored
statusintegerNo1 = 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

FieldDescription
accessYour access level on the document: full, edit, view, comment or none
publishPublic URL if the document is published, otherwise null
type / type_label1 = Document, 2 = Proposal
template_type1 = Prebuilt template, 2 = Custom template, 3 = PDF upload
status / status_label1 = Draft, 2 = In Progress, 3 = Completed
signersSigners attached to the document (for signable documents)

Create a Document

Create a new document.

POST /api/public-v1/documents

Request Body

FieldTypeRequiredDescription
namestringYesDocument name (max 191 characters)
visibilityintegerYes0 = Private, 1 = Public, 2 = Team Only
typeintegerNo1 = Document (default), 2 = Proposal
is_signablebooleanNoWhether the document can be signed (default: true)
is_self_signablebooleanNoWhether the owner can self-sign (default: false)
template_typeintegerNo1 = Prebuilt (default), 2 = Custom, 3 = PDF upload
statusintegerNo1 = Draft (default), 2 = In Progress
mediaintegerNoID 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:

FieldTypeDescription
expired_atdatetime stringExpiry date (default: 15 days from now)
send_in_orderbooleanSigners must sign in order (default: false)
template_idstringTemplate name used to prefill the document blocks
teamsarrayTeam IDs to attach to the document
signersarraySigner 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: 422 with {"error": {"name": ["The name field is required."]}}.
  • Plan document limit reached: 422 with {"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

ParameterTypeRequiredDescription
uuidstringYesDocument 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

ParameterTypeRequiredDescription
uuidstringYesDocument 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

ParameterTypeRequiredDescription
uuidstringYesDocument UUID

Request Body

FieldTypeRequiredDescription
blocksarrayYesOrdered list of block objects
blocks[].idstringYesBlock UUID (client generated)
blocks[].typestringYesBlock type (for example paragraph, heading, table)
blocks[].propsobjectYesBlock properties
blocks[].contentarrayNoBlock content
blocks[].childrenarrayYesNested 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

FieldTypeRequiredDescription
namestringYesNew 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"]}} when name is missing, not a string, or longer than 191 characters
  • 404 {"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

FieldTypeRequiredDescription
folder_idstringYesID 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"]}} when folder_id is missing
  • 404 {"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

FieldTypeRequiredDescription
user_idintegerYesID of the user
access_typeintegerYes (unless removing)1 full, 2 edit, 3 view, 4 comment (see Access Type Values). An invalid value returns 422
actionstringNoSend 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"} when access_type is not a valid access type value
  • 422 {"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"]}}
  • 422 plan 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.pdf

JavaScript 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

FieldTypeRequiredDescription
invitationTypeintegerYes1 = Team member, 2 = Contact, 3 = Team
invitationTypeIdintegerYesID of the team member’s user, the contact’s user, or the team (depending on invitationType)
actionTypeintegerYes0 = invite / update access, 1 = revoke access. Send a JSON integer
access_typeintegerNo1 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 found
  • You don't have permission to invite anyone to this document
  • User not found
  • This 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

FieldTypeRequiredDescription
actionTypeintegerYes0 = 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

FieldTypeRequiredDescription
typeintegerYes0 = emoji, 1 = uploaded image
emojistringRequired if type is 0Emoji character
media_idintegerRequired if type is 1ID 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_id are required for the matching type)
  • 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

FieldTypeRequiredDescription
typeintegerYes0 = import from an image URL, 1 = use an already uploaded media file
image_urlstringRequired if type is 0Image URL to import
media_idintegerRequired if type is 1ID 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/user

Request Body

FieldTypeRequiredDescription
namestringYesName of the mentioned user
document_uuidstringYesUUID of the document
emailstringYesEmail 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 CodeDescription
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"}
422Validation errors ({"error": {"field": ["..."]}}) and permission/business-rule errors ({"error": {"msg": ["..."]}})
503Workspace is in read-only maintenance and the request is a write

Document Object

FieldTypeDescription
idintegerDocument ID
uuidstringDocument UUID used in URLs
created_byobjectOwner (id, name, image, type, email, contact_id)
folderobjectid, uuid, name (all null when not in a folder)
namestringDocument name
visibilityobjectid (0/1/2) and label
permissionsarrayUsers with access (user_id, access_type, user), including members of attached teams
created_atstringFormatted date (for example Jan 15, 2024, 09:30 AM)
accessstringCurrent user’s access: full, edit, view, comment, none
publishstring|nullPublic URL when published
teamsarrayAttached teams with id, name, access_type, members
type, type_labelinteger, stringDocument (1) or Proposal (2)
is_signable, is_self_signable, send_in_order, is_editablebooleanSigning and editing flags
template_typeinteger1, 2 or 3
status, status_labelinteger, stringDraft (1), In Progress (2), Completed (3)
expired_atstringExpiry date (for example Jan 30, 2024)
signersarraySigners
Last updated on