V2 Workspace API

• In order to get your workspaceId, go to /workspaces, click to workspace clipboard icon. It copies your workspaceId to clipboard.
• In order to get your clusterId, select workspace, go to clusters tab, select the cluster, then on the cluster details section click to clipboard icon.

Table of Contents

1. Authentication and Headers
2. Common Behavior
3. Get Workspace
4. List Articles
5. Get Article by ID
6. List Clusters
7. Get Cluster by ID
8. List Cluster Articles
9. List Author Identities
10. Get Author Identity by ID
11. List Author Identity Articles
12. Get Digest Settings
13. Update Digest Settings
14. Create Analytics Event
15. OPTIONS / CORS

Authentication and Headers

Use one of the following headers:

• x-api-key: ai_xxx
• Authorization: Bearer ai_xxx

Required headers:

• Content-Type: application/json for POST and PUT

Common Behavior

• Every endpoint is workspace-scoped: /api/v2/workspaces/:workspaceId/...
• List endpoints return pagination:
  • skip (default 0, min 0)
  • limit (default 20, min 1, max 100)
• Most responses include rate-limit headers.

Common error responses:

• 400 invalid path/query/body
• 401 invalid or missing API key
• 402 workspace has reached monthly API access quota
• 403 API key workspace scope does not match path workspace
• 404 resource not found
• 429 rate limited

1) Get Workspace

Method: GET Path: /api/v2/workspaces/:workspaceId

Description

Returns the foundational workspace identity context for everything else in the reference. Use this endpoint to anchor scope, naming, and baseline context before shaping downstream interaction flows.

Use Cases

• Establish a consistent workspace anchor for experience mapping and information hierarchy.
• Feed naming and context labels used across navigation, command surfaces, and visual grouping.
• Confirm source-of-truth scope before rendering stateful interaction layers.

Path Params

• workspaceId (ObjectId)

Success Response (200)

{
	"workspace": {
		"id": "665b7db6a8f0a98a5ef2c111",
		"name": "My Workspace"
	}
}

cURL

curl -X GET "https://www.inkpilots.com/api/v2/workspaces/<workspaceId>" \
	-H "x-api-key: <apiKey>"

2) List Articles

Method: GET Path: /api/v2/workspaces/:workspaceId/articles

Description

Returns a workspace-wide paginated inventory of narrative units across all clusters and author identities. Use this endpoint as the broad discovery layer for cross-topic composition and curation.

Use Cases

• Build a master content canvas with rich sorting and filtering interactions.
• Curate high-signal sets for featured story flows and highlighted experiences.
• Feed quality and consistency passes that evaluate content at portfolio scale.

Query Params

• skip, limit
• sortBy: createdAt | updatedAt | title | status
• sortOrder: asc | desc
• clusterId: ObjectId or null
• status: draft | published | archived
• language: string
• model: string
• tags: comma-separated values
• slug: string
• search: string

Success Response

• Returns { articles, pagination }

3) Get Article by ID

Method: GET Path: /api/v2/workspaces/:workspaceId/articles/:articleId

Description

Returns one narrative unit by id within workspace scope. Use this endpoint when a detailed surface needs complete context for one selected item.

Use Cases

• Hydrate a deep detail canvas with structure, metadata, and current lifecycle state.
• Support precise edit and review loops on a single narrative artifact.
• Validate targeted references when linking related visual experiences.

Errors

• 400 Invalid articleId
• 404 Article not found

4) List Clusters

Method: GET Path: /api/v2/workspaces/:workspaceId/clusters

Description

Returns a paginated set of thematic clusters used to structure editorial intent. This endpoint supports visual planning through filters such as cycle alignment and content density.

Use Cases

• Build thematic navigation systems that guide user attention across major pillars.
• Visualize which clusters are content-rich versus content-sparse.
• Create cycle-aware planning views for phased storytelling.

Query Params

• skip, limit
• sortBy: name | createdAt | updatedAt (default updatedAt)
• sortOrder: asc | desc
• search: string
• contentCycleId: ObjectId
• color: string
• hasArticles: true | false

Success Response

• Returns { clusters, pagination }

5) Get Cluster by ID

Method: GET Path: /api/v2/workspaces/:workspaceId/clusters/:clusterId

Description

Returns the full profile for a single thematic cluster. Use this endpoint when one focused theme needs complete context before sequencing related narratives.

Use Cases

• Populate cluster overview panels with definitive taxonomy and identity data.
• Validate cluster linkages before assigning narrative units.
• Refresh one thematic context after updates to labels or structure.

Errors

• 400 Invalid clusterId
• 404 Cluster not found

6) List Cluster Articles

Method: GET Path: /api/v2/workspaces/:workspaceId/clusters/:clusterId/articles

Description

Returns the narrative corpus mapped to one cluster with pagination and filters. This endpoint isolates a single theme so progression and balance can be assessed clearly.

Use Cases

• Build theme-specific story arcs that show sequence and maturity.
• Track movement between lifecycle states inside one cluster lane.
• Create comparative visuals that reveal depth and coverage per theme.

Query Params

• Same article list filters as section 2 (skip, limit, sort, status, language, model, tags, slug, search)

Errors

• 400 Invalid clusterId or invalid query params
• 404 Cluster not found

7) List Author Identities

Method: GET Path: /api/v2/workspaces/:workspaceId/author-identities

Description

Returns a paginated list of voice identities configured for the workspace. Use this endpoint to drive attribution logic and persona-based narrative consistency.

Use Cases

• Build voice selection controls that shape tone and perspective.
• Visualize persona readiness by profile completeness and media presence.
• Segment identity sets by ownership for cleaner operational governance.

Query Params

• skip, limit
• sortBy: name | createdAt | updatedAt (default updatedAt)
• sortOrder: asc | desc
• search: string
• createdByUserId: ObjectId
• hasImage: true | false

Success Response

• Returns { authorIdentities, pagination }

8) Get Author Identity by ID

Method: GET Path: /api/v2/workspaces/:workspaceId/author-identities/:authorIdentityId

Description

Returns one voice identity by id with complete profile context. Use this endpoint when a focused persona surface requires canonical detail.

Use Cases

• Render detailed identity cards with signature tone and presentation traits.
• Validate persona references before finalizing attribution in narrative flows.
• Load authoritative identity context into editorial decision points.

Errors

• 400 Invalid authorIdentityId
• 404 Author identity not found

9) List Author Identity Articles

Method: GET Path: /api/v2/workspaces/:workspaceId/author-identities/:authorIdentityId/articles

Description

Returns narrative units associated with one voice identity. This endpoint keeps retrieval scoped to a single persona, improving signal clarity for tone analysis.

Use Cases

• Curate persona-specific content streams with consistent voice characteristics.
• Compare contribution rhythm and thematic spread for one identity.
• Build targeted review lanes for drafts tied to a selected voice.

Query Params

• Same article list filters as section 2 (skip, limit, sort, status, language, model, tags, slug, search)

Errors

• 400 Invalid authorIdentityId or invalid query params
• 404 Author identity not found

10) Get Digest Settings

Method: GET Path: /api/v2/workspaces/:workspaceId/digest

Description

Returns the current digest configuration that defines summary cadence and sender identity. Use this endpoint to understand how periodic narrative rollups are currently orchestrated.

Use Cases

• Initialize configuration surfaces with current cadence and sender values.
• Verify rollout behavior before adjusting communication rhythm.
• Present operational summary states for team alignment and review.

Success Response (200)

{
	"digest": {
		"workspaceId": "665b7db6a8f0a98a5ef2c111",
		"enabled": false,
		"frequency": "weekly",
		"subject": "Weekly workspace digest",
		"previewText": "Highlights from your workspace",
		"senderName": "Inkpilot",
		"replyTo": "team@example.com",
		"createdAt": "2026-05-14T00:00:00.000Z",
		"updatedAt": "2026-05-14T00:00:00.000Z"
	}
}

11) Update Digest Settings

Method: PUT Path: /api/v2/workspaces/:workspaceId/digest

Description

Updates digest behavior parameters for cadence, identity, and summary presentation. Use this endpoint to keep recurring narrative delivery aligned with brand and audience rhythm.

Use Cases

• Persist cadence adjustments as communication strategy evolves.
• Activate or pause recurring summary streams during operational shifts.
• Refine sender and reply routing for trust, clarity, and ownership.

Request Body

{
	"enabled": true,
	"frequency": "weekly",
	"subject": "Weekly update",
	"previewText": "This week in your workspace",
	"senderName": "Inkpilot Team",
	"replyTo": "team@example.com"
}

Body rules:

• enabled: boolean (required)
• frequency: daily | weekly | monthly (required)
• subject: string, 1..180 (required)
• previewText: string, max 280 (optional)
• senderName: string, 1..120 (required)
• replyTo: valid email, max 200 (optional)

Errors

• 400 Invalid JSON body
• 400 Invalid request body
• 500 Failed to update digest settings

12) Create Analytics Event

Method: POST Path: /api/v2/workspaces/:workspaceId/analytics

Description

Creates an analytics event record enriched with contextual attribution metadata. Use this endpoint to capture behavioral signals that inform experiential refinement.

Use Cases

• Measure how users move through narrative and interaction sequences.
• Attribute engagement changes to specific campaign or channel signals.
• Feed insight loops that improve visual hierarchy and flow decisions.

Request Body

{
	"visitorId": "visitor_123456",
	"articleId": "665b7db6a8f0a98a5ef2c112",
	"page": {
		"type": "workspace",
		"path": "/dashboard",
		"host": "yourdomain.com",
		"siteSlug": "docs",
		"articleSlug": "my-post"
	},
	"utm": {
		"utm_source": "newsletter"
	},
	"client": {
		"screen": "1920x1080"
	},
	"landingUrl": "https://yourdomain.com"
}

Body rules:

• visitorId: string, 6..128 (required)
• articleId: ObjectId (optional)
• page.type: workspace | article | unknown (optional)
• utm: object (optional)
• client: object (optional)
• landingUrl: string, max 2000 (optional)

Success Response (201)

{
	"analytics": {
		"inserted": true
	}
}

Errors

• 400 Invalid JSON body
• 400 Invalid request body

OPTIONS / CORS

Description

Provides the preflight contract for method and header compatibility checks. Use this behavior to confirm transport expectations before operational calls are executed.

Use Cases

• Verify compatibility between external clients and API access policies.
• Diagnose blocked calls caused by mismatched headers or method declarations.
• Certify integration readiness during reliability and QA passes.

All route files expose OPTIONS and return 204 No Content with CORS headers.

Allowed methods and headers:

• Methods: GET, POST, PUT, OPTIONS
• Headers: Authorization, Content-Type, X-API-KEY

Quick Start Example

# 1) list articles
curl -X GET "https://www.inkpilots.com/api/v2/workspaces/<workspaceId>/articles?status=published&sortBy=updatedAt&sortOrder=desc" \
	-H "x-api-key: <apiKey>"

# 2) send analytics event
curl -X POST "https://www.inkpilots.com/api/v2/workspaces/<workspaceId>/analytics" \
	-H "x-api-key: <apiKey>" \
	-H "Content-Type: application/json" \
	-d '{"visitorId":"visitor_123456","page":{"type":"workspace","path":"/dashboard"}}'