API Documentation

Everything you need to integrate natural language workout parsing into your app.

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header as a Bearer token.

Request Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

🔑 Getting Your API Key

API keys are organization-scoped and should be kept secure. Never expose your API key in client-side code. If you need an API key, request early access at reppie.app.

POST

/api/v1/parse_workout

Parse free-form workout descriptions into structured exercise data.

Request

curl -X POST https://api.reppie.app/api/v1/parse_workout \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "3 sets of 12 push-ups and 20kg goblet squats"}'

Parameters

Name Type Required Description
text string Yes Free-form workout description. Minimum 1 character after trimming.

Response (200 OK)

{
  "version": "v1",
  "request_id": "req_01JF7A8K6ZQY",
  "text": "3 sets of 12 push-ups and 20kg goblet squats",
  "parsed_at": "2025-01-14T10:41:12Z",
  "exercises": [
    {
      "exercise_id": 1,
      "name": "Push-up",
      "matched": true,
      "raw_name": "push-ups",
      "raw_segment": "3 sets of 12 push-ups",
      "sets": 3,
      "reps": 12,
      "weight": null,
      "weight_unit": null,
      "duration_seconds": null,
      "per_side": false
    },
    {
      "exercise_id": 42,
      "name": "Goblet Squat",
      "matched": true,
      "raw_name": "goblet squats",
      "raw_segment": "20kg goblet squats",
      "sets": null,
      "reps": null,
      "weight": 20,
      "weight_unit": "kg",
      "duration_seconds": null,
      "per_side": false
    }
  ],
  "metadata": {
    "model": "gpt-4o-mini",
    "prompt_tokens": 123,
    "completion_tokens": 45
  }
}

Error Responses

422 Unprocessable Entity

{ "error": "text param is required" }

401 Unauthorized

Missing or invalid API key.

429 Too Many Requests

Rate limit or quota exceeded. See Rate Limiting section.

503 Service Unavailable

LLM service failure or upstream error.

GET

/api/v1/exercises

List canonical exercises available for matching.

Request

curl -X GET "https://api.reppie.app/api/v1/exercises?page=1&per_page=25&q=squat" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Name Type Default Description
page integer 1 Page number (must be ≥ 1)
per_page integer 25 Results per page (max: 50)
q string - Search query (case-insensitive)
primary_muscle_group string - Filter by muscle group

Response (200 OK)

{
  "version": "v1",
  "request_id": "req_01JF7AJ9ZC4S",
  "exercises": [
    {
      "id": 101,
      "name": "Air Squat",
      "category": "strength",
      "equipment": "bodyweight",
      "primary_muscle_group": "quadriceps",
      "secondary_muscles": "glutes,hamstrings",
      "default_units": "reps"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_count": 87,
    "total_pages": 4
  }
}
GET

/api/v1/usage

Retrieve current usage statistics for your organization.

Request

curl -X GET https://api.reppie.app/api/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

{
  "period_start": "2025-01-01",
  "period_end": "2025-01-31",
  "request_count": 432,
  "monthly_quota": 1000,
  "percentage_used": 43.2,
  "requests_per_second": 10,
  "requests_per_minute": 600,
  "plan": "Starter"
}

💡 The usage endpoint does not count against your monthly quota, but is still subject to rate limiting.

Rate Limiting & Quotas

Rate Limits by Plan

Plan Requests/Second Requests/Minute Monthly Quota
Free 2 120 1,000
Starter 10 600 10,000
Growth 25 1,500 100,000
Custom 100 6,000 Unlimited*

* Custom plans have configurable quotas (default: unlimited)

429 Error Response

When rate limits are exceeded:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: 10 requests per second",
  "retry_after": 1
}

The Retry-After header indicates seconds to wait before retrying.

Error Handling

HTTP Status Codes

200

OK

Request succeeded

401

Unauthorized

Missing or invalid API key

422

Unprocessable Entity

Invalid parameters (missing text, unpermitted params)

429

Too Many Requests

Rate limit or quota exceeded

503

Service Unavailable

LLM service failure or upstream error

Need Help?

Questions about the API? Want to request a feature? We're here to help.

Contact Support