Getting Started

This guide covers the conventions and patterns you'll encounter when working with the Keep'em API. For authentication setup, see Authentication.

Base URL

All API requests are made to:

https://api.keepem.io/v1

Request format

Errors

The API returns errors in RFC 7807 Problem Details format with Content-Type: application/problem+json.

{
  "type": "https://keepem.io/docs/api-reference/errors#validation-error",
  "title": "Bad Request",
  "status": 400,
  "detail": "Property 'name' is required but is missing.",
  "instance": "/v1/events",
  "errors": [
    {
      "field": "name",
      "message": "required field"
    }
  ]
}

Error fields

HTTP status codes

Rate limits

API requests are rate limited to ensure fair usage. When you exceed the limit, you'll receive a 429 response.

Rate limit headers

Every response includes rate limit information:

Handling rate limits

When you receive a 429 response:

1. Read the Retry-After header for the wait duration
2. Wait the specified number of seconds
3. Retry the request

For production integrations, implement exponential backoff with jitter to avoid thundering herd issues when multiple clients retry simultaneously.

Pagination

List endpoints return paginated results. Use query parameters to control pagination:

curl "https://api.keepem.io/v1/events?page=2&limit=10" \
  -H "X-API-Key: sk_live_your_secret_key"

Responses include pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 10,
    "total": 142,
    "totalPages": 15
  }
}

Idempotency

For POST requests that create resources, you can pass an Idempotency-Key header to safely retry requests without creating duplicates.

curl -X POST https://api.keepem.io/v1/events \
  -H "X-API-Key: sk_live_your_secret_key" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Event"}'

• Keys are valid for 24 hours
• Repeating a request with the same key returns the original response
• Use UUIDs or another unique identifier as the key value

Versioning

The API is versioned via the URL path (/v1). Non-breaking changes (new optional fields, new endpoints) may be added without a version bump. Breaking changes will be introduced in new versions.

Next steps