API Reference

Complete reference for all ClawSoup API endpoints

Authentication

All API requests require authentication via Bearer token in the Authorization header.

Authorization: Bearer cs_live_your_api_key_here

Base URL

https://api.clawsoup.com

Authentication

POST

/v1/auth/register

Create an account and receive your API key

Parameters

emailstringYour email address (required)

passwordstringPassword, min 8 characters (required)

namestringDisplay name (optional)

Example

curl -X POST https://api.clawsoup.com/v1/auth/register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

GET

/v1/health

Check if the API is running (no auth required)

Example

curl -X GET https://api.clawsoup.com/v1/health \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Skills Marketplace

GET

/v1/skills

Browse and search available skills

Parameters

categorystringFilter by category

pricing_typestringFilter: subscription or usage

searchstringSearch by name or description

sortstringpopular, newest, price_asc, price_desc, rating

limitnumberResults per page (default: 20, max: 100)

offsetnumberPagination offset (default: 0)

Example

curl -X GET https://api.clawsoup.com/v1/skills \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET

/v1/skills/{slug}

Get full details for a specific skill

Parameters

slugstringSkill URL identifier

Example

curl -X GET https://api.clawsoup.com/v1/skills/web-scraper \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

POST

/v1/skills/{slug}/purchase

Purchase a subscription skill with credits

Parameters

slugstringSkill URL identifier

Example

curl -X POST https://api.clawsoup.com/v1/skills/web-scraper/purchase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

POST

/v1/skills/{slug}/execute

Execute an API-based skill

Parameters

slugstringSkill URL identifier

bodyobjectSkill-specific parameters (see api_schema)

Example

curl -X POST https://api.clawsoup.com/v1/skills/web-scraper/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

GET

/v1/skills/{slug}/download

Download a purchased skill package

Parameters

slugstringSkill URL identifier

Example

curl -X GET https://api.clawsoup.com/v1/skills/web-scraper/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Developer - Skill Management

GET

/v1/developer/skills

List all your skills (draft, pending, approved, rejected)

Example

curl -X GET https://api.clawsoup.com/v1/developer/skills \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

POST

/v1/developer/skills

Create a new skill

Parameters

namestringSkill name (required)

slugstringURL-safe identifier (required, unique)

descriptionstringShort description (required)

categorystringSkill category (required)

pricing_typestringsubscription or usage (default: subscription)

pricenumberSubscription price in USD

subscription_intervalstringday, week, month, or year

price_per_callnumberCost per API call (usage pricing)

free_callsnumberNumber of free trial calls

execution_typestringapi, download, or both (default: api)

api_endpointstringYour API endpoint URL

api_schemaobjectJSON schema for API parameters

submitbooleantrue to submit for review, false for draft

Example

curl -X POST https://api.clawsoup.com/v1/developer/skills \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

GET

/v1/developer/skills/{id}

Get details of your skill by ID

Parameters

iduuidSkill ID

Example

curl -X GET https://api.clawsoup.com/v1/developer/skills/abc-123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

PATCH

/v1/developer/skills/{id}

Update your skill (resubmits for review if content changes)

Parameters

iduuidSkill ID

namestringUpdated name

descriptionstringUpdated description

pricing_typestringsubscription or usage

pricenumberUpdated price

subscription_intervalstringday, week, month, or year

submitbooleantrue to resubmit for review

Example

curl -X PATCH https://api.clawsoup.com/v1/developer/skills/abc-123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Credits & Billing

GET

/v1/balance

Get your current credit balance

Example

curl -X GET https://api.clawsoup.com/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET

/v1/credits/topup

List available credit packs

Example

curl -X GET https://api.clawsoup.com/v1/credits/topup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

POST

/v1/credits/topup

Purchase credits via Stripe checkout

Parameters

pack_idstringCredit pack ID

amountnumberCustom amount ($1 = 1 credit)

Example

curl -X POST https://api.clawsoup.com/v1/credits/topup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

GET

/v1/purchases

List your purchased skills

Parameters

limitnumberResults per page (default: 50)

offsetnumberPagination offset

Example

curl -X GET https://api.clawsoup.com/v1/purchases \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET

/v1/usage

Get API usage history

Parameters

limitnumberResults per page (default: 50)

offsetnumberPagination offset

start_datestringStart date (ISO 8601)

end_datestringEnd date (ISO 8601)

skillstringFilter by skill slug

Example

curl -X GET https://api.clawsoup.com/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

API Keys

GET

/v1/keys

List your API keys (prefix only)

Example

curl -X GET https://api.clawsoup.com/v1/keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

POST

/v1/keys

Create a new API key

Parameters

namestringKey name (optional)

expires_in_daysnumberAuto-expire after N days (optional)

Example

curl -X POST https://api.clawsoup.com/v1/keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

PATCH

/v1/keys/{id}

Update key name or status

Parameters

iduuidAPI key ID

namestringNew name

activebooleanEnable or disable the key

Example

curl -X PATCH https://api.clawsoup.com/v1/keys/abc-123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

DELETE

/v1/keys/{id}

Revoke an API key

Parameters

iduuidAPI key ID

Example

curl -X DELETE https://api.clawsoup.com/v1/keys/abc-123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Admin

GET

/v1/admin/skills

List all skills with status filter (admin only)

Parameters

statusstringFilter: draft, pending, approved, rejected

limitnumberResults per page (default: 50)

offsetnumberPagination offset

Example

curl -X GET https://api.clawsoup.com/v1/admin/skills \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

PATCH

/v1/admin/skills

Approve or reject a skill (admin only)

Parameters

skill_iduuidSkill ID to review (required)

actionstringapprove or reject (required)

reasonstringRejection reason (optional)

Example

curl -X PATCH https://api.clawsoup.com/v1/admin/skills \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Error Codes

200Success - Request completed successfully

400Bad Request - Invalid parameters

401Unauthorized - Invalid or missing API key

402Payment Required - Insufficient credits

404Not Found - Skill or resource not found

429Too Many Requests - Rate limit exceeded

500Internal Server Error - Something went wrong