API Documentation

Authentication

The API uses token authentication. Manage your tokens from the API tokens page.

Pass the token in the Authorization header on every request:

Authorization: Bearer {your-token}

Base URL

https://blogtrottr.com/api

All endpoints are relative to this base. Requests must include Accept: application/json.

Pagination

List responses are paginated at 100 items per page:

{
  "data": [ ... ],
  "links": {
    "first": "https://...",
    "last":  "https://...",
    "prev":  null,
    "next":  "https://...?page=2"
  },
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 100,
    "total": 250
  }
}

Use the page query parameter to navigate pages.

Field Reference

schedule

output

digest_sort

Only applicable when schedule is a digest type. Ignored for asap.

Filter object

The filter field on subscriptions and categories is a structured content filter. When a filter is enabled, each incoming feed item is tested against it; items that do not pass are skipped.

Top-level structure

Group

Rule

Example

Permit only items whose title contains "AI" or "machine learning":

{
  "version": 2,
  "enabled": true,
  "action": "permit",
  "group_operator": "or",
  "groups": [
    {
      "operator": "or",
      "rules": [
        { "field": "item_title", "operator": "contains", "value": "AI" },
        { "field": "item_title", "operator": "contains", "value": "machine learning" }
      ]
    }
  ]
}

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["version", "enabled", "action", "group_operator", "groups"],
  "additionalProperties": false,
  "properties": {
    "version":        { "type": "integer", "const": 2 },
    "enabled":        { "type": "boolean" },
    "action":         { "type": "string", "enum": ["permit", "deny"] },
    "group_operator": { "type": "string", "enum": ["and", "or"] },
    "groups": {
      "type": "array",
      "maxItems": 5,
      "items": {
        "type": "object",
        "required": ["operator", "rules"],
        "additionalProperties": false,
        "properties": {
          "operator": { "type": "string", "enum": ["and", "or"] },
          "rules": {
            "type": "array",
            "minItems": 1,
            "maxItems": 250,
            "items": {
              "type": "object",
              "required": ["field", "operator", "value"],
              "additionalProperties": false,
              "properties": {
                "field":    { "type": "string", "enum": ["item_title", "item_body", "item_url", "author", "category"] },
                "operator": { "type": "string", "enum": ["contains", "not_contains", "regex", "not_regex"] },
                "value":    { "type": "string", "minLength": 1, "maxLength": 500 }
              }
            }
          }
        }
      }
    }
  }
}

Note: the 500-rule total limit across all groups and the 200-character cap on regex patterns cannot be expressed in JSON Schema and are enforced server-side.

Errors

All errors return JSON:

{
  "message": "The url field is required.",
  "errors": {
    "url": ["The url field is required."]
  }
}

Feed discovery failures return:

{
  "message": "Feed not found.",
  "details": { ... }
}

HTTP status codes

List subscriptions

Returns a paginated list of subscriptions.

Query parameters

Example response

{
  "data": [
    {
      "id": "aabbccddeeff001122334455",
      "enabled": true,
      "url": "https://example.com/feed.rss",
      "schedule": "asap",
      "output": "email",
      "digest_sort": null,
      "from": null,
      "subject_format": null,
      "title_only": false,
      "user_title": null,
      "filter": { "version": 2, "enabled": false, ... },
      "email_address_id": null,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "links": { ... },
  "meta": { ... }
}

Get subscription

Returns a single subscription.

Create subscription

Creates a new subscription. The feed URL will be discovered and normalised — if it resolves or redirects to a different URL than submitted, the final URL will be used.

Request body (JSON)

Example request

POST /api/subscriptions
Content-Type: application/json
Authorization: Bearer {token}

{
  "url": "https://example.com/feed.rss",
  "schedule": "asap",
  "output": "email"
}

Responses

Update subscription

Partially updates a subscription. Only include the fields you want to change — all fields are optional.

Request body (JSON)

Responses

Delete subscription

Permanently deletes a subscription.

List email addresses

Returns a paginated list of additional email addresses on the account. Use the id field as the email_address_id when creating or updating subscriptions.

Query parameters

Example response

{
  "data": [
    {
      "id": "aabbccddeeff001122334455",
      "email": "[email protected]",
      "enabled": true,
      "created_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "links": { ... },
  "meta": { ... }
}

Get email address

Returns a single email address.

Example response

{
  "data": {
    "id": "aabbccddeeff001122334455",
    "email": "[email protected]",
    "enabled": true,
    "created_at": "2024-01-15T10:30:00.000000Z"
  }
}

List categories

Returns a paginated list of the account's subscription categories, ordered by name.

Example response

{
  "data": [
    {
      "id": "aabbccddeeff001122334455",
      "name": "Tech",
      "filter": null,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "links": { ... },
  "meta": { ... }
}

Get category

Returns a single category.

Create category

Request body (JSON)

Responses

Update category

Partially updates a category. Only include the fields you want to change.

Request body (JSON)

Responses

Delete category

Permanently deletes a category. Any subscriptions assigned to it will have their category_id set to null.