API Overview

The Justack API is a RESTful API that allows you to create sessions, send messages, and manage recipients programmatically.

Base URL

https://api.justack.dev/v1

Authentication

All API requests require authentication using an API key in the Authorization header:

curl https://api.justack.dev/v1/sessions \
  -H "Authorization: Bearer jstk_xxxxxxxxxxxxx"

API keys are available in the Dashboard. Keys use the jstk_ prefix.

Request Format

• All requests must include Content-Type: application/json
• Request bodies must be valid JSON
• Timestamps use ISO 8601 format

curl https://api.justack.dev/v1/sessions \
  -H "Authorization: Bearer jstk_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Session", "recipients": ["user@example.com"]}'

Response Format

Success Response (Single Resource)

{
  "session_id": "01HXYZ...",
  "name": "My Session",
  "retention_months": 1,
  "created_at": "2024-01-15T10:00:00Z",
  "expires_at": "2024-02-14T10:00:00Z"
}

List Response (Cursor-Based Pagination)

{
  "data": [
    { "session_id": "01HXYZ...", "name": "Session 1" },
    { "session_id": "01HABC...", "name": "Session 2" }
  ],
  "next_cursor": "01HABC..."
}

When next_cursor is null, there are no more results.

Error Response

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "name is required"
  }
}

Error Codes

HTTP Status	Code	Description
400	BAD_REQUEST	Malformed request or invalid params
401	UNAUTHORIZED	Missing or invalid API key
402	PAYMENT_REQUIRED	Usage limit reached for your tier
403	FORBIDDEN	API key lacks required permissions
404	NOT_FOUND	Resource doesn’t exist
429	RATE_LIMITED	Too many requests
500	(varies)	Server error

Usage Limits

Limits are based on your account tier:

Resource	Free	Pro
Recipients	10	100
Sessions	25	250
Messages / month	10,000	100,000
Invites / month	50	500
API keys	3	20
Max retention	1 month	12 months

Check your current usage via the /v1/usage endpoint.

Endpoints

Sessions

Method	Endpoint	Description
POST	/v1/sessions	Create a session
GET	/v1/sessions	List sessions
GET	/v1/sessions/:id	Get session details
DELETE	/v1/sessions/:id	Delete a session

Messages

Method	Endpoint	Description
POST	/v1/sessions/:id/messages	Send a message
GET	/v1/sessions/:id/messages	List messages

Recipients

Method	Endpoint	Description
POST	/v1/recipients	Create a recipient
GET	/v1/recipients	List recipients
GET	/v1/recipients/:id	Get recipient details
DELETE	/v1/recipients/:id	Delete a recipient
POST	/v1/recipients/:id/invite	Send invite email
POST	/v1/recipients/:id/invite-url	Get invite URL

WebSocket

Method	Endpoint	Description
GET	/v1/sessions/:id/ws	Session WebSocket (API key or recipient token)
GET	/v1/inbox/ws	Inbox WebSocket (recipient token)

Usage

Method	Endpoint	Description
GET	/v1/usage	Get current usage and limits

Other

Method	Endpoint	Description
GET	/health	Health check
POST	/v1/auth/magic-link	Request magic link (public)

Pagination

List endpoints use cursor-based pagination:

# First page
curl "https://api.justack.dev/v1/sessions?limit=20"

# Next page (use next_cursor from previous response)
curl "https://api.justack.dev/v1/sessions?limit=20&after=01HXYZ..."

Parameter	Type	Default	Max	Description
limit	number	20	100	Number of items to return
after	string	-	-	Cursor from previous next_cursor

Endpoint Details

Create Session

POST /v1/sessions

Request Body:

Field	Type	Required	Description
name	string	Yes	Display name (1-255 chars)
retention_months	number	No	Retention period, 1-12 (default: 1)
recipients	array	No	Recipient strings or objects
notify	boolean	No	Send email notifications (default: false)
callback_url	string	No	Webhook callback URL

Recipients can be:

• A string: email address, external ID, or recipient ID
• An object: { "email": "..." } or { "external_id": "..." }

Response (201):

{
  "session_id": "01HXYZ...",
  "name": "My Session",
  "retention_months": 1,
  "created_at": "2024-01-15T10:00:00.000Z",
  "expires_at": "2024-02-14T10:00:00.000Z",
  "recipients": [
    {
      "recipient_id": "01HABC...",
      "name": "user@example.com",
      "email": "user@example.com",
      "external_id": null,
      "created_at": "2024-01-15T10:00:00.000Z"
    }
  ]
}

Create Recipient

POST /v1/recipients

Request Body:

Field	Type	Required	Description
name	string	Yes	Display name (1-255 chars)
email	string	No*	Email address
external_id	string	No*	External identifier (max 255 chars)

*At least one of email or external_id is required.

Response (201):

{
  "recipient_id": "01HABC...",
  "name": "John Doe",
  "email": "john@example.com",
  "external_id": null,
  "created_at": "2024-01-15T10:00:00.000Z"
}

Send Message

POST /v1/sessions/:sessionId/messages

Request Body:

Field	Type	Required	Description
role	string	Yes	"agent" or "recipient"
type	string	Yes	"log" or "ask"
content	string	Yes	Message content (1 byte - 1MB)
inputs	string	No	JSON-encoded input definitions (for ask)
persist	boolean	No	Whether to persist the message (default: true)

Response (201):

{
  "id": "01HDEF...",
  "role": "agent",
  "type": "ask",
  "content": "Deploy to production?",
  "inputs": "[{\"type\":\"confirm\",\"name\":\"approved\"}]",
  "response_content": null,
  "responded_at": null,
  "responded_by": null,
  "persist": true,
  "created_at": "2024-01-15T10:00:00.000Z"
}

Get Usage

GET /v1/usage

Response:

{
  "tier": "free",
  "usage": {
    "recipients": { "current": 3, "limit": 10 },
    "sessions": { "current": 5, "limit": 25 },
    "messages": { "current": 150, "limit": 10000, "resets_at": "2024-02-01T00:00:00.000Z" },
    "invites": { "current": 2, "limit": 50, "resets_at": "2024-02-01T00:00:00.000Z" }
  }
}

Next Steps

• TypeScript SDK - SDK reference and examples
• Sessions Guide - Session management concepts
• Recipients Guide - Recipient management