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 agentId, select workspace, go to agents tab, click to agent clipboard icon to copy agentId to clipboard automatically.
• 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 Agents
5. Get Agent by ID
6. List Agent Articles
7. List Articles
8. Get Article by ID
9. List Clusters
10. Get Cluster by ID
11. List Cluster Articles
12. List Author Identities
13. Get Author Identity by ID
14. List Author Identity Articles
15. List Social Posts
16. Get Social Post by Slug
17. Get Digest Settings
18. Update Digest Settings
19. Create Analytics Event
20. 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 Agents

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

Description

Returns a paginated catalog of automation actors with sort and filter controls. This endpoint is ideal for building comparative and decision-oriented views of active operational entities.

Use Cases

• Compose control surfaces that segment actors by status, model, and execution behavior.
• Build visual prioritization lanes that highlight active versus inactive ownership patterns.
• Drive selection workflows before opening deep detail context for one actor.

Query Params

• skip, limit
• sortBy: name | createdAt | updatedAt | model | isActive | executionMode (default createdAt)
• sortOrder: asc | desc (default desc)
• status: active | inactive
• executionMode: scheduled | batched
• model: string
• search: string

Success Response (200)

{
	"agents": [],
	"pagination": {
		"skip": 0,
		"limit": 20,
		"totalCount": 0,
		"totalPages": 1,
		"currentPage": 1,
		"hasNextPage": false,
		"hasPrevPage": false
	}
}

3) Get Agent by ID

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

Description

Returns the full profile for a single actor identified by agentId in workspace scope. Use this endpoint when a focused view needs authoritative, high-fidelity metadata for one entity.

Use Cases

• Populate a detailed inspector panel with exact behavior and identity context.
• Validate references before linking orchestrations to a specific actor.
• Refresh one focused visual card after state transitions.

Path Params

• workspaceId (ObjectId)
• agentId (ObjectId)

Errors

• 400 Invalid agentId
• 404 Agent not found

4) List Agent Articles

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

Description

Returns a paginated set of narrative outputs associated with one specific actor. Filtering and sorting remain constrained to the actor context, enabling focused production analysis.

Use Cases

• Build actor-centric timelines that show flow from draft states to published states.
• Create review queues segmented by language and quality stage.
• Design compact output matrices for focused performance storytelling.

Query Params

• skip, limit
• sortBy: createdAt | updatedAt | title | status
• sortOrder: asc | desc
• status: draft | published | archived
• language: string
• model: string
• slug: string
• agentId: ObjectId (accepted by schema, but this endpoint already scopes to path agentId)
• clusterId: ObjectId or null
• tags: comma-separated values
• search: string

Errors

• 400 Invalid agentId or query parameters
• 404 Agent not found

5) List Articles

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

Description

Returns a workspace-wide paginated inventory of narrative units across all clusters and actors. 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
• agentId: ObjectId
• 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 }

6) 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

7) 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 }

8) 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

9) 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 5 (skip, limit, sort, status, language, model, tags, slug, search, agentId)

Errors

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

10) 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 }

11) 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

12) 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 5 (skip, limit, sort, status, language, model, tags, slug, search, agentId)

Errors

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

13) List Social Posts

Method: GET Path: /api/v2/workspaces/:workspaceId/social-posts

Description

Returns a paginated collection of short-form distribution assets. Slot filters (square, portrait, landscape) make it easy to align output with visual format intent.

Use Cases

• Build format-aware asset boards for rapid creative selection.
• Design visual systems that pivot by aspect ratio and campaign moment.
• Organize and retrieve concise promotional narratives with predictable structure.

Query Params

• skip, limit
• sortBy: title | createdAt | updatedAt (default updatedAt)
• sortOrder: asc | desc
• search: string
• selectedImageSlot: square | portrait | landscape
• createdByUserId: ObjectId

Success Response

• Returns { socialPosts, pagination }

14) Get Social Post by Slug

Method: GET Path: /api/v2/workspaces/:workspaceId/social-posts/:postSlug

Description

Returns one short-form asset resolved by a stable slug. Slug-based access supports durable references in collaborative flows and content handoffs.

Use Cases

• Retrieve a specific creative artifact from human-readable references.
• Resolve handoff links used in editorial and design collaboration.
• Validate identifier continuity across revisions and publishing cycles.

Path Params

• postSlug: non-empty string

Errors

• 400 Invalid postSlug
• 404 Social post not found

15) 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"
	}
}

16) 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

17) 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",
	"agentId": "665b7db6a8f0a98a5ef2c113",
	"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)
• agentId: ObjectId (optional)
• page.type: workspace | article | agent | 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 agents
curl -X GET "https://www.inkpilots.com/api/v2/workspaces/<workspaceId>/agents?limit=20&skip=0" \
	-H "x-api-key: <apiKey>"

# 2) 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>"

# 3) 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"}}'