Outlign

Outlign API

v1.0 Documentation

Documents API

Documents are rich-text pages — briefs, specs, meeting notes, reports. A document always belongs to a company, and may optionally be attached to a project or a client. Document bodies are exchanged as Markdown.

Internal vs client-facing

Every document carries its own is_internal flag. Documents are created as internal (team-only) by default. A document is only visible to client users when is_internal is false. Internal documents are never returned to client-side tokens, in either list or single responses. Only agency team members can create, delete, or change the visibility of a document.

The Document Object

{
  "id": 42,
  "uuid": "9f1c1b2e-6f5a-4a1c-9a4b-2f8c1d0e7a55",
  "title": "Discovery Brief",
  "excerpt": "Kick-off summary and scope for the Acme rebrand...",
  "is_internal": true,
  "edit_access": "team",
  "created_at": "2026-01-01T12:00:00.000000Z",
  "updated_at": "2026-01-04T09:30:00.000000Z",
  "author": {
    "id": 7,
    "name": "Dave Prince"
  },
  "project": {
    "id": 789,
    "title": "Website Redesign"
  },
  "client": null,
  "company": {
    "id": 202,
    "title": "Design Studio Inc"
  }
}

Attributes

Attribute Type Description
id integer Unique identifier for the document
uuid string The document's public identifier. Documents are addressed by UUID in URLs, not by id
title string The document's title
content string The document body as Markdown. Only returned when you pass ?include=content
excerpt string A plain-text excerpt of the body (first 200 characters)
is_internal boolean true = team-only. false = visible to the client
edit_access string One of private, team, or collaborative (clients may edit)
author object The user who created the document
project object The project the document is attached to (nullable)
client object The client the document is attached to (nullable)
company object The company that owns the document
created_at string ISO 8601 timestamp when the document was created
updated_at string ISO 8601 timestamp when the document was last updated

Markdown bodies

Document bodies are stored as rich text and exchanged over the API as Markdown. Two things follow from this:

  • Sending content on an update replaces the entire body. Fetch the document with ?include=content first and send back the full revised Markdown.
  • Rich elements that Markdown cannot express — file attachments, embedded documents, and form fields — are preserved. Even though your Markdown omits them, they are kept in place, so a round-trip edit never silently deletes what a human added. To remove them deliberately, pass allow_removing_attachments: true.

Documents are collaboratively edited in Outlign. When you replace the body of a document that has an active collaborative editing history, that history is reset and anyone with the document open should reload it.

List Documents

Retrieves documents the authenticated user has access to, most recently updated first.

GET /api/v1/documents

Query Parameters

Parameter Type Description
company_id integer Filter to a company you have access to. Returns 403 otherwise
project_id integer Filter to documents attached to a project
client_id integer Filter to documents attached to a client
is_internal boolean Filter to internal or client-facing documents
include string Pass content to include each document's Markdown body
per_page integer Results per page

Example Request

curl -X GET "https://go.outlign.co/api/v1/documents?project_id=789" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"

Retrieve a Document

Fetches a single document by its UUID. Returns 404 if the document does not exist or you do not have access to it.

GET /api/v1/documents/{uuid}

Example Request

curl -X GET "https://go.outlign.co/api/v1/documents/9f1c1b2e-6f5a-4a1c-9a4b-2f8c1d0e7a55?include=content" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"

Create a Document

Creates a document. Only agency team members may create documents. The document is created as internal (team-only) unless you explicitly pass is_internal: false.

POST /api/v1/documents

Body Parameters

Parameter Type Description
title string Required. The document title
content string The document body as Markdown
company_id integer Required unless project_id or client_id is given, in which case it is inferred
project_id integer Attach the document to a project. Must belong to the same company
client_id integer Attach the document to a client. Must belong to the same company
is_internal boolean Defaults to true (team-only). Pass false to make it visible to the client

Example Request

curl -X POST "https://go.outlign.co/api/v1/documents" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "title": "Discovery Brief",
    "content": "## Summary\n\nKick off the rebrand next week.",
    "project_id": 789,
    "is_internal": true
  }'

Returns 201 Created with the document object.

Update a Document

Updates a document's title, body, or visibility. Sending content replaces the entire body. Only agency team members may change is_internal or edit_access.

Attachments, form fields, and embeds are preserved on content updates. Markdown cannot express these elements, so when content replaces the body, any such elements in the existing content are kept in place even if your markdown omits them (elements retained as plain links are upgraded back to their original form). To remove them deliberately, pass allow_removing_attachments: true.

PUT /api/v1/documents/{uuid}

Body Parameters

Parameter Type Description
title string New title
content string New Markdown body. Replaces the whole body. Sending empty content on a document that has a body returns 422
is_internal boolean Changes who can see the document. Agency team members only
edit_access string One of private, team, collaborative. Agency team members only

Example Request

curl -X PUT "https://go.outlign.co/api/v1/documents/9f1c1b2e-6f5a-4a1c-9a4b-2f8c1d0e7a55" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "title": "Discovery Brief (v2)",
    "content": "## Summary\n\nScope confirmed with the client."
  }'

Delete a Document

Deletes a document and its attachments. Only agency team members may delete documents; client users receive a 403.

DELETE /api/v1/documents/{uuid} 
curl -X DELETE "https://go.outlign.co/api/v1/documents/9f1c1b2e-6f5a-4a1c-9a4b-2f8c1d0e7a55" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"