REST API v1

Interactive playground + full endpoint reference. Auth, rate limits, sessions, folders, history, search — with cURL/JS/Python examples.

Try the API live

Pick an endpoint, fill in parameters, hit Send Request — see the simulated response instantly.

Scroll down for complete endpoint reference, data models, and code samples.

Base URL

https://prompt-aura.ppai.web.id/api/v1

All endpoints below are relative to this base.

Authentication

Every request requires a valid API key in the Authorization header:

Authorization: Bearer pa_xxx...xxxx

Key format

• Prefix: pa_
• 32 lowercase hex characters
• Total: 35 characters
• Regex: ^pa_[a-f0-9]{32}$

Getting a key

1. Sign in to PromptAura web app
2. Go to Settings → API Keys
3. Click Create Key → name it → copy (shown once)
4. Store securely — cannot be retrieved again

Rate limiting

Rate limit headers

Every response includes:

429 response

{
  "error": "Rate limit exceeded",
  "retryAfter": 45
}

Wait until X-RateLimit-Reset before retrying.

Error format

All errors follow this structure:

{
  "error": "Human-readable message",
  "code": "ERROR_CODE",
  "details": {}
}

Common codes

Endpoints

GET /me

Get authenticated user + API key info.

curl -H "Authorization: Bearer ***" \
  https://prompt-aura.ppai.web.id/api/v1/me

Response (200):

{
  "user": {
    "id": "user-uuid",
    "name": "Hanif",
    "email": "user@example.com",
    "image": "https://.../avatar.png",
    "createdAt": "2026-01-15T08:00:00.000Z"
  },
  "apiKey": {
    "keyId": "key-uuid",
    "permissions": ["read"]
  }
}

GET /sessions

List sessions with optional folder filter & pagination.

# All sessions
curl -H "Authorization: Bearer ***" \
  "https://prompt-aura.ppai.web.id/api/v1/sessions"

# Filter by folder, paginate
curl -H "Authorization: Bearer ***" \
  "https://prompt-aura.ppai.web.id/api/v1/sessions?folderId=folder-uuid&limit=20&offset=0"

Query parameters:

Response (200):

{
  "sessions": [
    {
      "id": "session-uuid-001",
      "folderId": "folder-uuid-001",
      "title": "Bi-Weekly Best Ads",
      "rawPrompt": "Analyze the {{task}} and generate...",
      "variables": { "task": "Q3 marketing campaign" },
      "tags": ["ads", "marketing"],
      "stepNumber": 1,
      "sortOrder": 0,
      "usageNote": "Use for ad performance analysis",
      "isPublic": false,
      "authorName": "Hanif",
      "likes": 0,
      "createdAt": "2026-01-24T10:00:00.000Z",
      "updatedAt": "2026-05-12T14:30:00.000Z",
      "syncedAt": "2026-05-12T14:30:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "count": 12
  }
}

GET /sessions/:id

Get a single session by ID.

curl -H "Authorization: Bearer ***" \
  https://prompt-aura.ppai.web.id/api/v1/sessions/session-uuid-001

Response (200): Same session object as above.

404 if not found or not yours.

GET /folders

List all folders (flat list with parentId for nesting).

curl -H "Authorization: Bearer ***" \
  https://prompt-aura.ppai.web.id/api/v1/folders

Response (200):

{
  "folders": [
    {
      "id": "folder-uuid-001",
      "parentId": null,
      "name": "Marketing",
      "createdAt": "2026-02-01T09:00:00.000Z"
    },
    {
      "id": "folder-uuid-002",
      "parentId": "folder-uuid-001",
      "name": "Q3 Campaigns",
      "createdAt": "2026-06-15T12:00:00.000Z"
    }
  ]
}

GET /history

List prompt history (clipboard entries), newest first.

curl -H "Authorization: Bearer ***" \
  "https://prompt-aura.ppai.web.id/api/v1/history?limit=20"

Query parameters:

Response (200):

{
  "history": [
    {
      "id": "history-uuid-001",
      "content": "Write a product description for...",
      "timestamp": "2026-07-08T11:45:00.000Z",
      "tags": ["copywriting"]
    }
  ],
  "pagination": {
    "limit": 20,
    "count": 15
  }
}

GET /search

Search sessions by title (case-insensitive LIKE match).

curl -H "Authorization: Bearer ***" \
  "https://prompt-aura.ppai.web.id/api/v1/search?q=ads&limit=20"

Query parameters:

Response (200):

{
  "results": [
    {
      "id": "session-uuid-001",
      "folderId": "folder-uuid-001",
      "title": "Bi-Weekly Best Ads",
      "rawPrompt": "Analyze the {{task}} and generate...",
      "variables": { "task": "Q3 marketing campaign" },
      "tags": ["ads", "marketing"],
      "stepNumber": 1,
      "sortOrder": 0,
      "usageNote": "Use for ad performance analysis",
      "isPublic": false,
      "authorName": "Hanif",
      "likes": 0,
      "createdAt": "2026-01-24T10:00:00.000Z",
      "updatedAt": "2026-05-12T14:30:00.000Z",
      "syncedAt": "2026-05-12T14:30:00.000Z"
    }
  ],
  "query": "ads",
  "count": 3
}

400 if q missing or empty.

Data models

Session

Folder

History Entry

User

Code examples

cURL

# List sessions
curl -H "Authorization: Bearer ***" \
  https://prompt-aura.ppai.web.id/api/v1/sessions

# Get session
curl -H "Authorization: Bearer ***" \
  https://prompt-aura.ppai.web.id/api/v1/sessions/session-uuid

# Search
curl -H "Authorization: Bearer ***" \
  "https://prompt-aura.ppai.web.id/api/v1/search?q=marketing&limit=10"

JavaScript (fetch)

const API_BASE = 'https://prompt-aura.ppai.web.id/api/v1';
const API_KEY = 'pa_xxx...';

async function api(path, options = {}) {
  const res = await fetch(`${API_BASE}${path}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

// List sessions
const { sessions } = await api('/sessions?limit=50');

// Search
const { results } = await api('/search?q=coding&limit=10');

Python (requests)

import requests

API_BASE = 'https://prompt-aura.ppai.web.id/api/v1'
API_KEY = 'pa_xxx...'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json',
}

# List sessions
r = requests.get(f'{API_BASE}/sessions', headers=headers, params={'limit': 50})
r.raise_for_status()
sessions = r.json()['sessions']

# Search
r = requests.get(f'{API_BASE}/search', headers=headers, params={'q': 'coding', 'limit': 10})
results = r.json()['results']

Public endpoints (no auth)

Changelog