API Reference · v1

Getroster REST API

Read-only access to your creators, pitches and inbound briefs. Designed for syncing into your CRM, BI dashboard or any custom automation. Available on the Established (£599/mo) and Custom plans.

Getting started

Generate an API token from Settings → API tokens. Each token is shown once at creation — copy it immediately and store it as a secret (never commit to git).

Tokens look like roster_pk_ followed by 32 hex characters. They scope automatically to your agency — there's no separate workspace switching.

Authentication

Send the token in an Authorization header:

Authorization: Bearer roster_pk_a1b2c3d4e5f6...

Tokens that have been revoked return 401 Unauthorized. Tokens with no recent activity are flagged in the dashboard but still accepted.

Base URL

https://www.getroster.co.uk/api/v1

Rate limits

Soft rate limit of 60 requests per minute per token. Heavy operations (search, large list pulls) count as 2. Going over returns 429 Too Many Requests with a Retry-After header in seconds.

GET/creators

List active creators on your roster with platform stats embedded.

Query parameters

Name	Type	Description
status	string	Filter by status. One of: active, signed, exclusive, prospect, on_hiatus, archived. Default: all non-archived.
limit	number	Max rows. Default 100, max 500.

Example request

curl https://www.getroster.co.uk/api/v1/creators?status=active&limit=50 \
  -H "Authorization: Bearer roster_pk_..."

Example response

{
  "data": [
    {
      "id": "uuid",
      "name": "Lola Park",
      "handle": "lolapark",
      "niche": "Food & lifestyle",
      "location": "London",
      "status": "signed",
      "platform_stats": [
        { "platform": "tiktok", "followers": 184000, "engagement_rate": 4.2, "avg_views": 95000 },
        { "platform": "instagram", "followers": 62000, "engagement_rate": 3.1 }
      ],
      "updated_at": "2026-04-12T10:14:30Z"
    }
  ]
}

GET/creators/:id

Single creator with full detail (campaigns, rate card, audience demographics, samples).

Example request

curl https://www.getroster.co.uk/api/v1/creators/<uuid> \
  -H "Authorization: Bearer roster_pk_..."

Example response

{
  "id": "uuid",
  "name": "Lola Park",
  "platform_stats": [...],
  "audience_demographics": [...],
  "past_campaigns": [...],
  "rate_card_items": [...],
  "content_samples": [...]
}

GET/pitches

List pitches you've created. Includes status, view counts, brand contact details.

Query parameters

Name	Type	Description
status	string	Filter: draft / sent / viewed / won / lost.
limit	number	Default 100, max 500.

Example request

curl "https://www.getroster.co.uk/api/v1/pitches?status=won" \
  -H "Authorization: Bearer roster_pk_..."

Example response

{
  "data": [
    {
      "id": "uuid",
      "brand_name": "IKEA UK",
      "brand_contact_email": "sarah@ikea.co.uk",
      "status": "won",
      "view_count": 14,
      "first_viewed_at": "2026-04-08T09:12:00Z",
      "sent_at": "2026-04-07T16:00:00Z",
      "created_at": "2026-04-07T15:30:00Z"
    }
  ]
}

GET/briefs

List inbound briefs received from brands via your public roster page.

Query parameters

Name	Type	Description
status	string	Filter: new / reviewing / responded / converted / declined / spam.
limit	number	Default 100, max 500.

Example request

curl "https://www.getroster.co.uk/api/v1/briefs?status=new" \
  -H "Authorization: Bearer roster_pk_..."

Example response

{
  "data": [
    {
      "id": "uuid",
      "brand_name": "Lush Cosmetics",
      "contact_name": "Anya Patel",
      "contact_email": "anya@lush.com",
      "campaign_brief": "Spring 2026 vegan range...",
      "budget_range": "£15K–£30K",
      "timeline": "Live by mid-March",
      "priority_tier": "high",
      "status": "new",
      "created_at": "2026-04-12T08:34:11Z"
    }
  ]
}

Errors

All errors return JSON in the form:

{ "error": "Description of what went wrong" }

Status	Meaning
401	Missing or invalid Bearer token.
403	Token lacks the required plan tier (Established+).
404	Resource not found or not in your agency.
429	Rate limit hit. Honour the `Retry-After` header.
5xx	Server error. Retry with exponential backoff.

Need write endpoints?

v1 is read-only by design — most agencies want to pull data into Notion, Airtable, Hubspot or a custom dashboard. If you have a specific write use case, email hello@getroster.co.uk and we'll prioritise it.

Questions? hello@getroster.co.uk