AMP
GitHub
SDK Reference

REST API

Direct REST API reference for AMP.

Base URL

https://api.amp-protocol.dev/v1

Authentication

All requests require an Authorization header with your API key:

Authorization: Bearer amp_sk_live_your_key_here

Endpoints

POST /context

Request motivation-aware context for a user.

curl -X POST https://api.amp-protocol.dev/v1/context \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "task": "build a login page",
    "complexity": "medium",
    "taskType": "coding"
  }'

Request Body

{
  "userId": "string",        // Required
  "task": "string",          // Required
  "complexity": "string",    // Optional: "low" | "medium" | "high"
  "taskType": "string",      // Optional: e.g. "coding", "debugging"
  "metadata": {}             // Optional: any additional context
}

Response

{
  "requestId": "req_abc123",
  "suggestedFraming": "micro_task",
  "communicationStyle": "brief_directive",
  "complexity": "break_into_steps",
  "encouragement": "moderate",
  "confidence": 0.87,
  "rationale": "User has 85% completion rate with step-by-step guidance",
  "metadata": {
    "profilePhase": "optimised",
    "interactionCount": 47,
    "explorationMode": false
  }
}

POST /outcome

Report the outcome of a user interaction.

curl -X POST https://api.amp-protocol.dev/v1/outcome \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "req_abc123",
    "started": true,
    "completed": true,
    "timeToStart": 45,
    "flowState": true,
    "satisfaction": 0.9
  }'

Request Body

{
  "requestId": "string",     // Required
  "started": boolean,        // Required
  "completed": boolean,      // Optional
  "timeToStart": number,     // Optional: seconds
  "flowState": boolean,      // Optional
  "satisfaction": number,    // Optional: 0-1
  "metadata": {}             // Optional
}

Response

{
  "success": true,
  "message": "Outcome reported successfully"
}

PUT /profile/:userId

Update a user's motivation profile.

curl -X PUT https://api.amp-protocol.dev/v1/profile/user_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preferredFraming": "achievement",
    "communicationStyle": "brief_directive"
  }'

Response

{
  "userId": "user_123",
  "preferredFraming": "achievement",
  "communicationStyle": "brief_directive",
  "complexityPreference": "break_into_steps",
  "encouragementLevel": "moderate",
  "lastUpdated": "2024-01-15T10:30:00Z",
  "profileVersion": "2.1"
}

Error Responses

400 Bad Request

{
  "error": {
    "code": "INVALID_USER_ID",
    "message": "User ID is required",
    "statusCode": 400
  }
}

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "statusCode": 401
  }
}

429 Rate Limited

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "details": {
      "limit": 100,
      "window": "60s",
      "retryAfter": 42
    },
    "statusCode": 429
  }
}

Rate Limits

Rate limits are returned in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1642247400

Examples in Different Languages

cURL

# Get context
curl -X POST https://api.amp-protocol.dev/v1/context \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_123", "task": "build feature"}'

# Report outcome
curl -X POST https://api.amp-protocol.dev/v1/outcome \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId": "req_abc", "started": true, "completed": true}'

JavaScript (Fetch)

const response = await fetch('https://api.amp-protocol.dev/v1/context', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: 'user_123',
    task: 'build feature'
  })
});

const context = await response.json();

Python (Requests)

import requests

response = requests.post(
    'https://api.amp-protocol.dev/v1/context',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'userId': 'user_123',
        'task': 'build feature'
    }
)

context = response.json()

💡 Recommendation: Use the official SDKs when possible. They handle authentication, retries, and error handling automatically.

See Also