v0.2.3-beta

Intelligence Unleashed

brainful API library

Quick navigation

overview getting started authentication create block append to block get block get inspired

overview

The brainful API enables seamless integration between your applications and brainful's powerful content management system. Whether you're building automation tools or integrating with your favorite apps, our RESTFUL API provides a simple and secure way to interact with your content.

Key features

Secure authentication

Token-based authentication with https encryption

Restful design

Standard http methods with json responses

Location support

Built-in geolocation capabilities

Rate limited

Optimised for reliable performance

Use cases

Personal automation

Auto-save notes from your favorite apps
Create location-based content triggers
Connect with IFTTT/Zapier workflows

Integration solutions

Build custom integrations and extensions
Create automated content workflows
Develop content management systems

Requirements

Rate limits

60 requests per minute per user

Getting started

Get your api token

Visit your brainful options page to generate your api token.

Choose your integration method

Select from our example code in cURL, JavaScript, or Python to get started quickly.

Make your first request

Try out the interactive examples below to test your integration.

authentication

All API requests require your API token in the Authorization header. Get your token from the brainful options page. The api supports both token and bearer token formats.

Your api token:

Authorization: Token YOUR_API_TOKEN

Authorization: Bearer YOUR_API_TOKEN

create block

POSThttps://brainful.dev/blocks/add

Request parameters

All parameters are sent in the request body as JSON.

Parameter	Type	Required	Description
string	string	Yes	Content to be added (1-5000 characters)
parent_luid	string	No	luid of the parent block (optional)
latitude	float	No	latitude (-90° to 90°)
longitude	float	No	longitude (-180° to 180°)
agent	string	No	Agent identifier (max 50 chars)
team_space	string	No	Team space slug to add the block to (only for organization members)

String content:Parent block luid: latitude (degrees, -90° to 90°): longitude (degrees, -180° to 180°): agent (up to 255 chars):Team space slug:

Generated Request

Example response

{
                    "luid": "abc123",
                    "slug": "My New Block",
                    "type": "thought",
                    "pinned": false,
                    "entities": [],
                    "created_timestamp": "2024-01-01T00:00:00Z",
                    "last_edited": "2024-01-01T00:00:00Z",
                    "experience": 5,
                    "remaining_daily_quota": 97
                  }

Response fields

luid

Type: string

Unique identifier for the created content

slug

Type: string

URL-friendly version of the content

words

Type: integer

Number of words in the content

remaining_daily_quota

Type: integer

Remaining content creation quota for today

Response codes

201Created (success)

400Bad request (invalid string)

401Unauthorised (invalid token)

403Forbidden (plan not sufficient)

422Invalid location coordinates

append to block

POSThttps://brainful.dev/blocks/append

Request parameters

All parameters are sent in the request body as JSON.

Parameter	Type	Required	Description
identifier	string	Yes	Identifier of the block to append to (luid or slug)
string	string	Yes	Content to be appended (1-5000 characters)

Example response

{
  "details": "Text appended to block successfully.",
  "luid": "abc123",
  "slug": "my-example-block"
}

Response fields

luid

Type: string

Unique identifier for the created content

slug

Type: string

URL-friendly version of the content

words

Type: integer

Number of words in the content

remaining_daily_quota

Type: integer

Remaining content creation quota for today

Response codes

201Created (success)

400Bad request (invalid string)

401Unauthorised (invalid token)

403Forbidden (plan not sufficient)

get block

GEThttps://brainful.dev/blocks/get/{luid}

Request parameters

URL Parameters

Parameter	Type	Required	Description
luid	string	Yes	Unique identifier of the block to retrieve

Request body

Parameter	Type	Required	Description
latitude	float	No	latitude (-90° to 90°)
longitude	float	No	longitude (-180° to 180°)
agent	string	No	Agent identifier (max 50 chars)

block LUID (6 chars): latitude (degrees, -90° to 90°): longitude (degrees, -180° to 180°): agent (up to 255 chars):

Generated Request

Example response

{
  "creator": "johnnyappleseed",
  "luid": "abc123",
  "slug": "My New Block",
  "type": "thought",
  "html": "My New Block",
  "blocks": [],
  "entities": [],
  "flagged": false,
  "pinned": false,
  "archived": false,
  "trashed": false,
  "public": false,
  "created_timestamp": "2025-01-28 18:01",
  "last_edited": "2025-01-28 18:01",
  "words": 3,
  "bytes": 45,
  "hits": 0
}

Response fields

creator

Type: string

Username of the content creator

luid

Type: string

Unique identifier for the block

type

Type: string

Content type (e.g., "thought")

html

Type: string

HTML content of the block

created_timestamp

Type: string

Creation date and time

hits

Type: integer

Number of views

Response codes

200Success (block found)

401Unauthorised (invalid token)

403Forbidden (plan not sufficient)

404Not found (block not found)

Feel inspired?

Take a look at some of our official integrations built with brainful User APITake a look at some of our official integrations built with brainful User API here!