Quick Start: API

Get your first Feelr request working in under two minutes with nothing but curl.

1. Get an API Key

Create an API key from the admin API. You’ll need your admin token (set during deployment):


curl -X POST https://api.feelr.dev/admin/keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "my-agent"}'

Response:


{
  "success": true,
  "data": {
    "key": "fk_live_abc123...",
    "short": "abc123",
    "label": "my-agent",
    "tier": "free",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Save the key value — you won’t be able to see it again.

2. Store a Credential

Store an upstream credential so Feelr can call APIs on your behalf. For GitHub, that’s a Personal Access Token:


curl -X PUT https://api.feelr.dev/admin/credentials/github \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"token": "ghp_your_github_pat_here"}'

3. Make Your First Request

List your GitHub repositories:


curl https://api.feelr.dev/v1/github/repos.list \
  -H "X-Feelr-Key: fk_live_abc123..."

Response:


{
  "success": true,
  "data": [
    {
      "id": 123456,
      "name": "my-project",
      "full_name": "you/my-project",
      "private": false,
      "description": "A cool project",
      "language": "TypeScript",
      "default_branch": "main",
      "stargazers_count": 42
    }
  ],
  "meta": {
    "has_more": true,
    "cursor": "2",
    "request_id": "req_abc123"
  }
}

4. Pass Parameters

Actions accept parameters as query strings:


# List open issues for a specific repo
curl "https://api.feelr.dev/v1/github/issues.list?repo=owner/repo&state=open" \
  -H "X-Feelr-Key: fk_live_abc123..."
 
# Create an issue
curl -X POST https://api.feelr.dev/v1/github/issues.create \
  -H "X-Feelr-Key: fk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"repo": "owner/repo", "title": "Bug report", "labels": "bug"}'

5. Pagination

When meta.has_more is true, pass the cursor value to get the next page:


curl "https://api.feelr.dev/v1/github/repos.list?cursor=2" \
  -H "X-Feelr-Key: fk_live_abc123..."

Response Envelope

Every Feelr response uses the same shape:


{
  "success": true,
  "data": { ... },
  "meta": {
    "has_more": false,
    "request_id": "req_..."
  }
}

Error responses:


{
  "success": false,
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "No credential stored for github",
    "hint": "auth"
  },
  "meta": {
    "request_id": "req_..."
  }
}

Error codes: AUTH_REQUIRED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, UPSTREAM_ERROR, INTERNAL_ERROR.

Next Steps

Authentication — API key tiers and credential management
GitHub Connector — all 10 actions with params and examples
CLI Quick Start — prefer a terminal? Start here instead