Documentation

API Reference

Complete reference for the Techsstuff API

Introduction

The Techsstuff API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL: https://api.techsstuff.com/v1

Authentication

The Techsstuff API uses API keys to authenticate requests. You can view and manage your API keys in the Techsstuff Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication Example

All API requests must include your API key in the Authorization header

curl https://api.techsstuff.com/v1/analytics/metrics \
  -H "Authorization: Bearer YOUR_API_KEY"

API Endpoints

Analytics

GET /analytics/metrics

Retrieve analytics metrics for your account

Query Parameters

Parameter	Type	Required	Description
start_date	string	Yes	Start date in YYYY-MM-DD format
end_date	string	Yes	End date in YYYY-MM-DD format
metrics	array	No	Array of metrics to retrieve (e.g., pageviews, sessions)
interval	string	No	Time interval (day, week, month)

Example Request

GET /analytics/metrics?start_date=2023-01-01&end_date=2023-01-31&metrics=pageviews,sessions&interval=day

Example Response

{
  "data": [
    {
      "date": "2023-01-01",
      "pageviews": 1245,
      "sessions": 876
    },
    {
      "date": "2023-01-02",
      "pageviews": 1322,
      "sessions": 921
    },
    // ... more data points
  ],
  "meta": {
    "total_pageviews": 38762,
    "total_sessions": 24981
  }
}

GET /analytics/events

Retrieve custom events data

Query Parameters

Parameter	Type	Required	Description
start_date	string	Yes	Start date in YYYY-MM-DD format
end_date	string	Yes	End date in YYYY-MM-DD format
event_name	string	No	Filter by specific event name
limit	integer	No	Maximum number of events to return (default: 100)

Example Response

{
  "data": [
    {
      "event_name": "button_click",
      "timestamp": "2023-01-15T14:22:31Z",
      "properties": {
        "button_id": "signup",
        "page": "/landing"
      }
    },
    {
      "event_name": "form_submit",
      "timestamp": "2023-01-15T14:23:12Z",
      "properties": {
        "form_id": "contact",
        "success": true
      }
    },
    // ... more events
  ],
  "meta": {
    "total": 1245,
    "page": 1,
    "limit": 100
  }
}

Users

GET /users

List all users in your organization

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum number of users to return (default: 50)
offset	integer	No	Number of users to skip (default: 0)
role	string	No	Filter by user role (admin, member, etc.)

Example Response

{
  "data": [
    {
      "id": "usr_123456",
      "email": "[email protected]",
      "name": "John Doe",
      "role": "admin",
      "created_at": "2022-10-15T09:12:34Z",
      "last_login": "2023-01-20T14:22:31Z"
    },
    {
      "id": "usr_123457",
      "email": "[email protected]",
      "name": "Jane Smith",
      "role": "member",
      "created_at": "2022-11-05T15:45:22Z",
      "last_login": "2023-01-19T10:15:42Z"
    },
    // ... more users
  ],
  "meta": {
    "total": 24,
    "limit": 50,
    "offset": 0
  }
}

POST /users

Create a new user in your organization

Request Body

Parameter	Type	Required	Description
email	string	Yes	User's email address
name	string	Yes	User's full name
role	string	No	User's role (default: member)
send_invite	boolean	No	Whether to send an invitation email (default: true)

Example Request

POST /users
Content-Type: application/json

{
  "email": "[email protected]",
  "name": "New User",
  "role": "member",
  "send_invite": true
}

Example Response

{
  "data": {
    "id": "usr_123458",
    "email": "[email protected]",
    "name": "New User",
    "role": "member",
    "created_at": "2023-01-21T11:34:56Z",
    "invite_sent": true
  }
}

Error Handling

The Techsstuff API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with our servers.

HTTP Status Codes

Code	Description
200 - OK	Everything worked as expected
400 - Bad Request	The request was unacceptable, often due to missing a required parameter
401 - Unauthorized	No valid API key provided
403 - Forbidden	The API key doesn't have permissions to perform the request
404 - Not Found	The requested resource doesn't exist
429 - Too Many Requests	Too many requests hit the API too quickly
500, 502, 503, 504 - Server Errors	Something went wrong on our end

Error Response Format

When an error occurs, the API will return a JSON response with an error object containing details about the error.

{
  "error": {
    "code": "invalid_request",
    "message": "The request was unacceptable, often due to missing a required parameter.",
    "param": "start_date",
    "type": "validation_error"
  }
}

Rate Limits

The Techsstuff API implements rate limiting to protect our infrastructure and ensure fair usage across all users. Rate limits vary based on your subscription plan.

Plan	Rate Limit
Free	100 requests per minute
Starter	500 requests per minute
Professional	1,000 requests per minute
Enterprise	Custom rate limits

When you exceed your rate limit, the API will return a 429 Too Many Requests response. The response headers will include information about your rate limit status:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1611234567

Back to Documentation Next: Tutorials