🔌 PhPstrap API Guide

The PhPstrap API lets you query user data and account information programmatically. All endpoints live under /api/v1/ and return JSON.

---

🔑 Authentication

Every request (except /status) requires an API token. Pass it in one of two ways:

Option A — Authorization header (recommended)

Authorization: Bearer YOUR_API_TOKEN

Option B — Query string

GET /api/v1/me.php?api_key=YOUR_API_TOKEN

You can find or regenerate your token in the Admin → API Keys panel or on your account's profile/API page.

---

📡 Endpoints

GET /api/v1/status.php

Public endpoint. No authentication required. Returns API health and version info.

Example request

curl https://yoursite.com/api/v1/status.php

Example response

{
  "success": true,
  "data": {
    "status": "operational",
    "api_version": "v1",
    "app_version": "0.1.9",
    "timestamp": "2026-01-01T00:00:00+00:00",
    "caller": null
  }
}

If you include a valid token, caller will contain your user ID, name, and membership status.

---

GET /api/v1/me.php

Returns the authenticated user's profile, membership, and API usage stats.

Example request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://yoursite.com/api/v1/me.php

Example response

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Jane Smith",
    "email": "jane@example.com",
    "company": null,
    "phone": null,
    "membership": {
      "status": "premium",
      "expires": "2027-01-01 00:00:00"
    },
    "credits": 100.0,
    "timezone": "UTC",
    "language": "en",
    "avatar": null,
    "bio": null,
    "website": null,
    "verified": true,
    "verified_at": "2026-01-01 12:00:00",
    "member_since": "2025-06-01 09:00:00",
    "api": {
      "plan": "standard",
      "usage": 42,
      "limit": 1000,
      "remaining": 958,
      "reset_at": "2026-01-02T00:00:00+00:00"
    }
  },
  "meta": {
    "version": "v1",
    "timestamp": "2026-01-01T12:00:00+00:00"
  }
}

---

GET /api/v1/users.php

Returns a paginated list of users. Requires a reseller plan.

Query parameters

Parameter	Type	Description
id	integer	Return a single user by ID
email	string	Filter by partial email match
status	string	Filter by membership status: free, premium, lifetime
page	integer	Page number (default: 1)
per_page	integer	Results per page, 1–100 (default: 25)

Example — single user

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://yoursite.com/api/v1/users.php?id=3

Example — search by email

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://yoursite.com/api/v1/users.php?email=smith&page=1&per_page=10"

Example response (list)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Jane Smith",
      "email": "jane@example.com",
      "company": null,
      "phone": null,
      "membership": { "status": "premium", "expires": "2027-01-01 00:00:00" },
      "credits": 100.0,
      "verified": true,
      "is_active": true,
      "timezone": "UTC",
      "language": "en",
      "created_at": "2025-06-01 09:00:00",
      "last_login": "2026-01-01 11:00:00"
    }
  ],
  "meta": {
    "version": "v1",
    "timestamp": "2026-01-01T12:00:00+00:00",
    "pagination": {
      "total": 48,
      "page": 1,
      "per_page": 25,
      "pages": 2
    }
  }
}

---

⚡ Rate Limiting

Every response includes rate limit headers so you can track your usage:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets

When the limit is exceeded you'll receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

---

❌ Error Responses

All errors follow a consistent shape:

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "API token not recognised."
  }
}

HTTP Status	Code	Meaning
400	INVALID_PARAM	A query parameter is missing or malformed
401	MISSING_TOKEN	No API token was provided
401	INVALID_TOKEN	Token is unrecognised or has been revoked
403	FORBIDDEN	Your plan does not have access to this endpoint
403	ACCOUNT_INACTIVE	Your account has been deactivated
404	NOT_FOUND	The requested resource does not exist
405	METHOD_NOT_ALLOWED	Wrong HTTP method (all endpoints are GET)
429	RATE_LIMIT_EXCEEDED	Too many requests — check Retry-After
500	INTERNAL_ERROR	Server-side error — try again shortly
503	API_DISABLED	The API has been disabled by the administrator

---

🛠️ Troubleshooting

• 401 on every request? Double-check your token hasn't been regenerated or revoked in Admin → API Keys.
• 403 on /users? That endpoint requires a reseller plan — ask your administrator to assign one.
• 503 API Disabled? An admin has turned off the API globally via Admin → Settings → API.
• Unexpected 500? Check your server's PHP error log for details.

---

Need help? Join the community on GitHub.