Skip to main content

​
Overview

Organisations enable team collaboration by grouping users, jobs, and resources under a single account. Each user can belong to multiple organisations and switch between them.

​
List Organisations

GET /v1/organisations
Authorization: Bearer <token>

​
Response Fields

​
organisations
array
Array of organisations the user belongs to
​
active_organisation_id
string
ID of the currently active organisation for this user

​
Create Organisation

POST /v1/organisations
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "My Company"
}

​
Request Body

​
name
string
required
Organisation name (max 100 characters)

​
Behaviour

  • Creating user is automatically added as an admin member
  • New organisation is automatically set as the user’s active organisation

​
Switch Active Organisation

POST /v1/organisations/switch
Authorization: Bearer <token>
Content-Type: application/json

{
  "organisation_id": "org_456def"
}

​
Request Body

​
organisation_id
string
required
ID of organisation to switch to (user must be a member)

​
Get Current Organisation

GET /v1/organisations/current
Authorization: Bearer <token>

​
Response Fields

​
members
array
Organisation members
​
members[].id
string
User identifier
​
members[].email
string
User email address
​
members[].role
string
Member role: admin or member
​
usage
object
Current usage statistics
​
usage.jobs_this_month
integer
Number of jobs created this month
​
usage.pages_crawled_this_month
integer
Number of pages crawled this month

​
List Members

GET /v1/organisations/members
Authorization: Bearer <token>

​
Response Fields

​
members
array
Array of organisation members
​
current_user_id
string
ID of the authenticated user making the request
​
current_user_role
string
Role of the authenticated user in this organisation

​
Update Member Role

PATCH /v1/organisations/members/{member_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "role": "admin"
}

​
Path Parameters

​
member_id
string
required
User ID of the member to update

​
Request Body

​
role
string
required
New role: admin or member

​
Requirements

  • Only organisation admins can update member roles
  • Cannot change your own role
  • Organisation must always have at least one admin (cannot demote last admin)

​
Remove Member

DELETE /v1/organisations/members/{member_id}
Authorization: Bearer <token>

​
Path Parameters

​
member_id
string
required
User ID of the member to remove

​
Requirements

  • Only organisation admins can remove members
  • Organisation must always have at least one admin (cannot remove last admin)

​
List Invites

GET /v1/organisations/invites
Authorization: Bearer <token>

​
Response Fields

​
invites
array
Array of pending invites
​
invites[].invite_link
string
Full URL to send to the invitee

​
Create Invite

POST /v1/organisations/invites
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "[email protected]",
  "role": "member"
}

​
Request Body

​
email
string
required
Valid email address of person to invite
​
role
string
default:"member"
Role to assign: admin or member

​
Response Fields

​
email_delivery
string
Email delivery status: sent, failed, skipped

​
Behaviour

  • Invites expire after 7 days
  • Email is sent automatically via Loops (if configured)
  • Only organisation admins can create invites
  • Cannot invite users who are already members

​
Preview Invite (Public)

GET /v1/organisations/invites/preview?token=abc123

​
Query Parameters

​
token
string
required
Invite token from the invite link
This endpoint is public (no authentication required) so users can preview the invite before signing up or logging in.

​
Accept Invite

POST /v1/organisations/invites/accept
Authorization: Bearer <token>
Content-Type: application/json

{
  "token": "abc123"
}

​
Request Body

​
token
string
required
Invite token from the invite link

​
Response Fields

​
active_organisation_set
boolean
Whether the new organisation was set as active (may retry in background if false)

​
Revoke Invite

DELETE /v1/organisations/invites/{invite_id}
Authorization: Bearer <token>

​
Path Parameters

​
invite_id
string
required
Unique invite identifier

​
Get Usage

GET /v1/usage
Authorization: Bearer <token>

​
Response Fields

​
usage.daily_used
integer
Pages crawled today
​
usage.daily_limit
integer
Daily page limit for current plan
​
usage.monthly_used
integer
Pages crawled this month
​
usage.plan_id
string
Current subscription plan identifier

​
Get Usage History

GET /v1/usage/history?days=30
Authorization: Bearer <token>

​
Query Parameters

​
days
integer
default:30
Number of days of history to retrieve (max 365)

​
Update Plan

PUT /v1/organisations/plan
Authorization: Bearer <token>
Content-Type: application/json

{
  "plan_id": "professional"
}

​
Request Body

​
plan_id
string
required
Plan identifier (e.g., “starter”, “professional”, “enterprise”)

​
Requirements

  • Only organisation admins can update the plan
  • Plan must exist and be active

​
Get Available Plans

GET /v1/plans
This endpoint is public (no authentication required) for use on pricing pages.

​
Response Fields

​
plans
array
Array of available subscription plans
​
plans[].id
string
Plan identifier
​
plans[].display_name
string
Human-readable plan name
​
plans[].daily_page_limit
integer
Maximum pages per day
​
plans[].monthly_price_cents
integer
Monthly price in cents (0 for free plans)

Build docs developers (and LLMs) love

Get started for freeTalk to us