Joinways Tasks API
The Tasks API from Joinways — 2 operation(s) for tasks.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/joinways-app:joinways-app-tasks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Joinways Public Tasks API
version: 1.15.0
description: 'The Joinways REST API lets you read and manage your CRM and event data:
events, quotes, invoices, companies, contacts, leads (requests), venues,
catalog, tasks, reports and more. It is a **JSON over HTTPS** API described by
this OpenAPI 3.1 document, served at `https://joinways.app/openapi.yaml`
and rendered at `https://joinways.app/docs/api`. The same data is reachable from AI assistants through the Joinways MCP
server (`https://mcp.joinways.app`, guide at
`https://joinways.app/docs/claude-mcp`): both surfaces share the OAuth
server, the tokens, the scopes, the role permissions and the services of
the app, so a rule holds the same way in the app, in the REST API and in
MCP. ## Authentication
Every request needs a **Bearer token** in the `Authorization` header:
```
Authorization: Bearer jw_xxxxxxxx
```
Two token types work:
- **API key** (`jw_…`): an owner or admin creates one from **Settings →
Developers → API keys** in the workspace (guide:
`https://joinways.app/docs/api-keys`). An API key acts as the member
who created it: it carries the read and write scopes, and the **role
permissions its creator holds now** in the workspace (see below; a
creator who leaves the workspace takes the key''s access with them). It
does not expire unless you set an expiry, and can be revoked at any
time from the same page. - **OAuth 2.1 access token** (`jw_oat_…`): for apps acting on a user''s
behalf (Authorization Code + PKCE S256, same flow as the MCP server). - Authorization endpoint `https://joinways.app/oauth/authorize`, token
endpoint `https://joinways.app/api/oauth/token`, revocation
`https://joinways.app/api/oauth/revoke` (RFC 7009), metadata
`https://joinways.app/.well-known/oauth-authorization-server`. - **Clients**: register with Dynamic Client Registration
(`POST /api/oauth/register`), or use an https URL as `client_id`
(Client ID Metadata Document). - **Resource** (RFC 8707): send `resource=https://joinways.app/api/v1`
on the authorization and token requests to bind the token to this API
(a token bound to `https://mcp.joinways.app` is refused here, and the
other way round). An unknown resource is refused with
`invalid_target`. Protected resource metadata:
`https://joinways.app/.well-known/oauth-protected-resource/api/v1`. - **Refresh**: a client registered with the `refresh_token` grant gets a
refresh token (`jw_ort_…`) next to a **1 hour** access token. Each
refresh rotates the refresh token (the old one stops working); a
refresh token unused for 90 days expires. A client without the
refresh grant gets a **30 day** access token and re-runs the flow. A refresh may ask for fewer scopes: only the new access token is
narrowed. A user who left the workspace gets `invalid_grant` on
refresh, and the whole token family is revoked. - **Granted scope** = requested ∩ supported (`mcp.read`, `mcp.write`)
∩ registered by the client. - The authorization response carries `iss` (RFC 9207). The consent
screen shows the host of a metadata-document client, and warns when
the `redirect_uri` is on another domain. - A workspace owner sees and revokes connected apps in **Settings →
Developers → MCP → Connected apps**. A token is **bound to a single workspace**. You never pass an
`account_id`: the workspace comes from the token. The API is part of
the **Pro plan and the free trial**: a valid token of a workspace
without either is refused with `403 forbidden`, `details.reason:
plan_not_eligible`. Revocation takes effect within about a minute
across our infrastructure. Tokens are stored hashed (SHA-256) and shown
once. A `401` carries the RFC 6750 / RFC 9728 challenge:
```
WWW-Authenticate: Bearer resource_metadata="https://joinways.app/.well-known/oauth-protected-resource/api/v1", scope="mcp.read mcp.write"
```
## Scopes
| Scope | Grants |
|---|---|
| `mcp.read` | Every `GET` |
| `mcp.write` | Every `POST`, `PATCH`, `PUT`, `DELETE`, and reading (it implies `mcp.read`) |
API keys carry both scopes.'
contact:
name: Joinways
url: https://joinways.app
license:
name: Proprietary
x-logo:
url: /images/marketing/logo-header.svg
altText: Joinways
href: https://joinways.app
servers:
- url: https://joinways.app/api/v1
description: Production
security:
- bearerAuth: []
- oauth2:
- mcp.read
- mcp.write
tags:
- name: Tasks
paths:
/tasks:
get:
tags:
- Tasks
summary: List tasks
operationId: listTasks
description: Tasks of the workspace, newest first. Tasks of archived events are left out unless `include_archived_events` is true. **Role permission:** none (any member).
security:
- bearerAuth: []
- oauth2:
- mcp.read
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- name: status
in: query
description: One or more statuses (repeat the parameter or separate with commas).
schema:
type: array
items:
$ref: '#/components/schemas/TaskStatus'
style: form
explode: true
- name: event_id
in: query
schema:
type: string
format: uuid
- name: company_id
in: query
description: Tasks about this company.
schema:
type: string
format: uuid
- name: contact_person_id
in: query
description: Tasks about this contact.
schema:
type: string
format: uuid
- name: include_archived_events
in: query
schema:
type: boolean
default: false
responses:
'200':
description: Page of tasks (summary fields).
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Paginated'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TaskSummary'
'400':
$ref: '#/components/responses/BadRequest'
description: An id filter is not a UUID (`details.field` names it).
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
post:
tags:
- Tasks
summary: Create a task
operationId: createTask
description: Creates a task, optionally on an event (not archived) and assigned to a member; a task on an event gets a timeline entry. **Role permission:** `data.write`.
security:
- bearerAuth: []
- oauth2:
- mcp.write
x-required-permission: data.write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TaskCreate'
responses:
'201':
description: The created task.
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'400':
$ref: '#/components/responses/BadRequest'
description: Validation failed, `event_id` is not an event of the workspace, or the assignee is not a member.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/EventArchived'
'429':
$ref: '#/components/responses/RateLimited'
/tasks/{id}:
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
get:
tags:
- Tasks
summary: Get a task
operationId: getTask
description: The full task (description, notes, attachments, dependencies…). **Role permission:** none (any member).
security:
- bearerAuth: []
- oauth2:
- mcp.read
responses:
'200':
description: The task.
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
patch:
tags:
- Tasks
summary: Update a task
operationId: updateTask
description: Updates the given fields. A task of an archived event is read-only (`409`). **Role permission:** `data.write`.
security:
- bearerAuth: []
- oauth2:
- mcp.write
x-required-permission: data.write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TaskUpdate'
responses:
'200':
description: The updated task.
content:
application/json:
schema:
$ref: '#/components/schemas/Task'
'400':
$ref: '#/components/responses/BadRequest'
description: Validation failed, no field given, `event_id` is not an event of the workspace, or the assignee is not a member.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/EventArchived'
'429':
$ref: '#/components/responses/RateLimited'
delete:
tags:
- Tasks
summary: Delete a task
operationId: deleteTask
description: Deletes the task. A task of an archived event is read-only (`409`). **Role permission:** `data.write`.
security:
- bearerAuth: []
- oauth2:
- mcp.write
x-required-permission: data.write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
responses:
'204':
description: Deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/EventArchived'
'429':
$ref: '#/components/responses/RateLimited'
components:
headers:
RateLimitLimit:
description: Requests allowed in the current window (per workspace once authenticated, per IP before).
schema:
type: integer
example: 600
RateLimitReset:
description: When the window resets (ISO 8601).
schema:
type: string
format: date-time
example: '2026-10-04T14:31:00.000Z'
RateLimitRemaining:
description: Requests left in the current window.
schema:
type: integer
example: 0
RetryAfter:
description: Seconds to wait before retrying.
schema:
type: integer
example: 12
schemas:
LeadErrorReason:
type: string
description: 'Leads: convert, merge, link, status, create.'
enum:
- lead_not_found
- lead_locked
- invalid_venue
- invalid_dates
- venue_locked
- venue_unavailable
- lead_linked_elsewhere
- same_lead
- not_found
- lead_archived
- both_converted
- target_archived
- target_rejected
- target_event_closed
- other_venue_event
- access_denied
- event_not_found
- event_closed
- lead_moved_concurrently
- validation_requires_event
- lead_deleted
QuoteErrorReason:
type: string
description: '409 state refusals, 400 validation (`min_price` with `details.params`; `package_article`: the line is an article of a package, write the package line; `package_discount_amount`: a package takes a percent discount only), 402 plan.'
enum:
- platform_quote_read_only
- platform_quote_delete_forbidden
- platform_version_signed
- quote_conflict
- quote_changed
- quote_locked
- quote_signed
- quote_cancelled
- quote_not_cancellable
- quote_has_active_invoice
- quote_has_amendments
- quote_superseded
- amendment_in_flight
- amendment_nested
- parent_not_active
- parent_not_signed
- parent_fully_invoiced
- invalid_status
- not_a_platform_version
- event_closed
- event_archived
- platform_quote_no_document
- min_price
- invalid_location_item
- package_article
- package_discount_amount
- no_fields
- db_rule
- validation
- quotes_plan_required
TaskSummary:
type: object
description: A task as listed (`GET /tasks`).
properties:
id:
type: string
format: uuid
task_number:
type:
- integer
- 'null'
title:
type: string
example: Send the signed contract
status:
$ref: '#/components/schemas/TaskStatus'
priority:
$ref: '#/components/schemas/TaskPriority'
due_date:
type:
- string
- 'null'
format: date-time
start_date:
type:
- string
- 'null'
format: date-time
estimated_duration_minutes:
type:
- integer
- 'null'
event_id:
type:
- string
- 'null'
format: uuid
brief_id:
type:
- string
- 'null'
format: uuid
company_id:
type:
- string
- 'null'
format: uuid
contact_person_id:
type:
- string
- 'null'
format: uuid
location_id:
type:
- string
- 'null'
format: uuid
assigned_to_account_id:
type:
- string
- 'null'
format: uuid
description: The member the task is assigned to.
category:
type:
- string
- 'null'
created_at:
type:
- string
- 'null'
format: date-time
updated_at:
type:
- string
- 'null'
format: date-time
SignedQuoteImportErrorReason:
type: string
description: POST /events/{id}/quotes/import.
enum:
- quotes_plan_required
- event_not_found
- quote_not_found
- event_archived
- quote_not_signable
- duplicate_reference
- invalid_pdf
- invalid_amounts
- pdf_too_large
- forbidden
PlatformErrorReason:
type: string
description: Authentication and rate limits (403, 429).
enum:
- plan_not_eligible
- per-ip
- per-account-minute
- per-account-day
- email_rate_limited
TaskErrorReason:
type: string
enum:
- task_not_found
- event_not_found
- assignee_not_found
- event_archived
- no_fields
TaskUpdate:
type: object
description: Every field is optional; at least one is required.
properties:
title:
type: string
status:
$ref: '#/components/schemas/TaskStatus'
priority:
$ref: '#/components/schemas/TaskPriority'
due_date:
type: string
format: date-time
assigned_to_account_id:
type: string
format: uuid
event_id:
type: string
format: uuid
company_id:
type:
- string
- 'null'
format: uuid
description: The company the task is about; `null` unlinks.
contact_person_id:
type:
- string
- 'null'
format: uuid
description: The contact the task is about; `null` unlinks.
ErrorReason:
description: '`details.reason` of an error: snake_case lower case, the same value as the `code` of the matching MCP tool error. One list per domain.'
anyOf:
- $ref: '#/components/schemas/PlatformErrorReason'
- $ref: '#/components/schemas/EventErrorReason'
- $ref: '#/components/schemas/LeadErrorReason'
- $ref: '#/components/schemas/TaskErrorReason'
- $ref: '#/components/schemas/QuoteErrorReason'
- $ref: '#/components/schemas/CatalogErrorReason'
- $ref: '#/components/schemas/SignedQuoteImportErrorReason'
- $ref: '#/components/schemas/EmailErrorReason'
TaskStatus:
type: string
enum:
- todo
- in_progress
- waiting
- done
- cancelled
TaskPriority:
type: string
enum:
- low
- medium
- high
- urgent
TaskCreate:
allOf:
- $ref: '#/components/schemas/EventTaskCreate'
- type: object
properties:
event_id:
type: string
format: uuid
description: An event of the workspace, not archived.
company_id:
type:
- string
- 'null'
format: uuid
description: A company of the workspace the task is about.
contact_person_id:
type:
- string
- 'null'
format: uuid
description: A contact of the workspace the task is about.
EventTaskCreate:
type: object
required:
- title
properties:
title:
type: string
minLength: 1
example: Send the signed contract
due_date:
type: string
format: date-time
priority:
$ref: '#/components/schemas/TaskPriority'
default: medium
status:
$ref: '#/components/schemas/TaskStatus'
assigned_to_account_id:
type: string
format: uuid
description: A member of the workspace (`400` otherwise).
EventErrorReason:
type: string
description: Events, their sub-resources and the BEO.
enum:
- event_not_found
- event_archived
- event_not_archived
- event_has_dependencies
- venue_locked
- venue_required
- venue_unavailable
- invalid_venue_spaces
- invalid_dates
- invalid_timezone
- invalid_reference
- invalid_assignee
- invalid_stage
- platform_duplicate
- no_fields
- revenue_access_required
- version_conflict
Task:
description: A task with every stored field.
allOf:
- $ref: '#/components/schemas/TaskSummary'
- type: object
properties:
account_id:
type:
- string
- 'null'
format: uuid
description:
type:
- string
- 'null'
notes:
type:
- string
- 'null'
quote_id:
type:
- string
- 'null'
format: uuid
attachments:
type:
- array
- 'null'
items:
type: string
dependencies:
type:
- array
- 'null'
items:
type: string
format: uuid
cancelled_reason:
type:
- string
- 'null'
status_before_cancellation:
type:
- string
- 'null'
is_demo:
type: boolean
CatalogErrorReason:
type: string
description: 'Catalog writes, packages mostly. All `400` except `package_component` (`409`). `package_price_read_only`: the price and tax rate of a package come from its components, they are never sent (nor `pricing_mode` without `components`). `package_components_required`: a package needs at least one component (or `is_package: false`). `package_flag_required`: `components` sent for a plain item without `is_package: true`. `package_component_duplicate`: an item listed twice. `package_component_self`: the package among its own components. `package_component_not_found`: a component that is not an item of the package''s venue (unknown, another venue, another workspace). `package_component_is_package`: a package cannot contain a package. `package_component_vat_required`: a component has no tax rate and the venue no country to take one from. `package_price_zero`: the components add up to 0. `min_price_above_price`: `min_price` above the price of the package. `price_required`: a plain item (created, or a package turned back into one) without a price. `package_components_refused`: the database refused the composition (a rule above, lost to a concurrent change). `package_component` (409): the item is a component of a package; it cannot be deleted, nor become a package, before it is removed from that package.'
enum:
- package_price_read_only
- package_components_required
- package_flag_required
- package_component_duplicate
- package_component_self
- package_component_not_found
- package_component_is_package
- package_component_vat_required
- package_price_zero
- min_price_above_price
- price_required
- package_components_refused
- package_component
Error:
type: object
description: Standard error envelope returned on any non-2xx response.
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Stable machine-readable error code (see the Errors table).
enum:
- invalid_request
- unauthorized
- payment_required
- forbidden
- not_found
- conflict
- idempotency_conflict
- payload_too_large
- idempotency_key_reuse
- quota_exceeded
- rate_limited
- server_error
example: not_found
message:
type: string
description: Human-readable message (do not parse it). Generic on 5xx.
example: Event not found
details:
description: 'Structured details: field errors on validation (`formErrors`, `fieldErrors`), the query parameter at fault (`field`), `reason` (a stable code) on refusals, or `null`.'
oneOf:
- type: object
additionalProperties: true
properties:
reason:
$ref: '#/components/schemas/ErrorReason'
field:
type: string
description: The parameter or body field at fault.
- type: 'null'
EmailErrorReason:
type: string
description: POST /events/{id}/emails.
enum:
- event_not_found
- event_archived
- connection_not_found
- connection_inactive
- connection_cannot_send
- no_connection
- reconnect_required
- email_rate_limited
Paginated:
type: object
description: Envelope wrapping a page of results.
required:
- data
- pagination
properties:
data:
type: array
description: The page of results (item type depends on the endpoint).
items: {}
pagination:
type: object
required:
- page
- per_page
- total
- total_pages
properties:
page:
type: integer
description: Current 1-based page.
example: 1
per_page:
type: integer
description: Items per page.
example: 50
total:
type:
- integer
- 'null'
description: Total matching items across all pages (`null` only on a page past the last one, when unknown).
example: 1234
total_pages:
type:
- integer
- 'null'
example: 25
responses:
Unauthorized:
description: Missing, invalid, expired or revoked bearer token (`unauthorized`).
headers:
WWW-Authenticate:
description: RFC 6750 challenge pointing at the protected resource metadata (RFC 9728).
schema:
type: string
example: Bearer resource_metadata="https://joinways.app/.well-known/oauth-protected-resource/api/v1", scope="mcp.read mcp.write"
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: unauthorized
message: Invalid or expired token
details: null
EventArchived:
description: The event is archived, so read-only (`conflict`, `details.reason` `event_archived`). Unarchive it first (`POST /events/{id}/unarchive`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: conflict
message: 'Event is archived: unarchive it before editing it'
details:
reason: event_archived
NotFound:
description: Not found in this workspace, or the id of the path is not a UUID (`not_found`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: not_found
message: Event not found
details: null
Forbidden:
description: '`forbidden`: the token lacks the scope, its owner''s role lacks the permission named by the operation, or the workspace has neither the Pro plan nor a trial (`details.reason` `plan_not_eligible`).'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: forbidden
message: 'Missing required permission: quotes.manage'
details: null
RateLimited:
description: 'Too many requests (`rate_limited`). `details.reason`: `per-ip`, `per-account-minute`, `per-account-day`, or `email_rate_limited` (email budget). Always carries `Retry-After`: wait that many seconds.'
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: rate_limited
message: Too many requests
details:
reason: per-account-minute
BadRequest:
description: Validation failed (`invalid_request`). For a body that fails the schema, `details` holds `formErrors` and `fieldErrors`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: invalid_request
message: Validation failed
details:
formErrors: []
fieldErrors:
start_date:
- Required
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: 'Optional client-generated key (1 to 255 characters, e.g. a UUID v4) that makes the request idempotent for 24 hours: a retry with the same key replays the recorded response (marked `Idempotency-Replayed: true`) instead of executing the operation again. Same key with another body: `422 idempotency_key_reuse`; while the first request runs: `409 idempotency_conflict`. See the **Idempotency** section.
'
schema:
type: string
minLength: 1
maxLength: 255
example: 5b0c6f1e-2f4a-4c1e-9d3b-7a2e8f0c1d23
PerPage:
name: per_page
in: query
description: Items per page.
schema:
type: integer
minimum: 1
maximum: 500
default: 50
Page:
name: page
in: query
description: 1-based page number.
schema:
type: integer
minimum: 1
default: 1
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key or OAuth token
description: 'Paste a token in the `Authorization: Bearer …` header: an **API key** (`jw_…`, created in Settings → Developers → API keys, acting with the role of the member who created it) or an **OAuth 2.1 access token** (`jw_oat_…`). A token is bound to a single workspace.
'
oauth2:
type: oauth2
description: 'OAuth 2.1 authorization code grant with mandatory PKCE (S256). Access tokens are opaque strings prefixed `jw_oat_`, presented as `Authorization: Bearer …`: valid 1 hour with a refresh token (`jw_ort_…`, rotated on each use, 90 days idle), 30 days for a client without the refresh grant. Send `resource=https://joinways.app/api/v1` (RFC 8707). Clients register dynamically or use an https `client_id` (Client ID Metadata Document). Tokens are bound to a single workspace.
'
flows:
authorizationCode:
authorizationUrl: https://joinways.app/oauth/authorize
tokenUrl: https://joinways.app/api/oauth/token
refreshUrl: https://joinways.app/api/oauth/token
scopes:
mcp.read: Read the workspace data the member's role can read.
mcp.write: Create, update, delete and actions within the member's role (implies read).