REST API Reference

Toolblip API Docs

Integrate with the Toolblip API to list tools, fetch tool metadata, and authenticate users using simple JSON requests.

Base URLs

Current production

https://toolblip-api-production.up.railway.app

Custom domain after SSL is ready

https://api.toolblip.com

Use the Railway URL today for every example below. The endpoint paths and response shapes stay the same when the custom API domain is ready. Examples use placeholder credentials and tokens; replace them with your own values before running requests.

Authentication

Register or log in to receive a token, then send it in the Authorization header as Bearer YOUR_TOKEN. Keep tokens private and never send them in query strings.

Authorization header

Authorization: Bearer YOUR_TOKEN

Token lifecycle

# 1. Register or login to receive a token
TOKEN=$(curl -s -X POST "https://toolblip-api-production.up.railway.app/api/auth/login" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email":"[email protected]","password":"your-password"}' \
  | jq -r .token)

# 2. Use the token on protected endpoints
curl "https://toolblip-api-production.up.railway.app/api/auth/user" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

# 3. Revoke the token when done
curl -X POST "https://toolblip-api-production.up.railway.app/api/auth/logout" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Before you start

All endpoints are JSON over HTTPS and currently live under the /api path. Prefix every path below with https://toolblip-api-production.up.railway.app today; when SSL is ready, the same requests can use https://api.toolblip.com.

Public request

curl "https://toolblip-api-production.up.railway.app/api/tools" \
  -H "Accept: application/json"

Authenticated request

curl "https://toolblip-api-production.up.railway.app/api/auth/user" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Current base URL

https://toolblip-api-production.up.railway.app

Use this Railway production host today.

Future base URL

https://api.toolblip.com

Switch here once api.toolblip.com SSL is ready.

Path prefix

/api

Every documented endpoint below is relative to the active base URL.

Auth header

Authorization: Bearer YOUR_TOKEN

Required only on protected auth endpoints.

Content type

application/json

Send and receive JSON for POST requests.

Base URL strategy

Store the API host in one environment variable so you can switch from the Railway production URL to api.toolblip.com once SSL is live without changing endpoint paths.

Environment setup

# Current production API
BASE_URL="https://toolblip-api-production.up.railway.app"

# Planned custom domain after SSL is ready
BASE_URL="https://api.toolblip.com"

Response models

Toolblip wraps resources in top-level objects. Tools are returned under tool for a single item and under tools.tools for the directory list.

Tool

{
  "id": 1,
  "slug": "json-formatter",
  "name": "JSON Formatter",
  "description": "Format, validate, and prettify JSON data instantly.",
  "category": "Developer",
  "is_pro": false,
  "emoji": "🧰",
  "created_at": "2026-01-15T10:30:00.000000Z"
}

User

{
  "id": 42,
  "name": "Jane Doe",
  "email": "[email protected]",
  "is_pro": false
}

Endpoint overview

MethodPathAuthResponsePurpose

GET/api/toolsNone{ tools: { tools: [...] } }List all tools GET/api/tools/{slug}None{ tool }Get a single tool POST/api/auth/registerNone{ user, token }Register POST/api/auth/loginNone{ user, token }Login POST/api/auth/logoutBearer token{ message }Logout GET/api/auth/userBearer token{ user }Get authenticated user

Format

Send JSON bodies and set Content-Type: application/json for POST requests.

Responses

Set Accept: application/json for consistent JSON responses.

Auth

Protected endpoints require Authorization: Bearer YOUR_TOKEN. Tokens are returned by register and login.

Tools

Tool endpoints

Tools

List all tools

Returns the public Toolblip directory. The tool array is nested at tools.tools to match the app client contract.

No auth required200 OKResponse: { tools: { tools: [...] } }

GET/api/tools

Headers

NameValueWhen

Acceptapplication/jsonRecommended for all requests

Query parameters

ParameterTypeRequiredDescription

categorystringOptionalFilter tools by category slug or name.

searchstringOptionalSearch tool names and descriptions.

pagenumberOptionalPagination page number.

per_pagenumberOptionalNumber of tools to return per page.

curl

curl "https://toolblip-api-production.up.railway.app/api/tools" \
  -H "Accept: application/json"

JSON response

{
  "tools": {
    "tools": [
      {
        "id": 1,
        "slug": "json-formatter",
        "name": "JSON Formatter",
        "description": "Format, validate, and prettify JSON data instantly.",
        "category": "Developer",
        "is_pro": false,
        "emoji": "🧰",
        "created_at": "2026-01-15T10:30:00.000000Z"
      }
    ]
  }
}

Tools

Get a single tool

Fetch metadata for one tool by slug. Use the slug returned by GET /api/tools.

No auth required200 OKResponse: { tool }

GET/api/tools/{slug}

Headers

NameValueWhen

Acceptapplication/jsonRecommended for all requests

Path parameters

ParameterTypeRequiredDescription

slugstringRequiredTool slug, for example json-formatter.

curl

curl "https://toolblip-api-production.up.railway.app/api/tools/json-formatter" \
  -H "Accept: application/json"

JSON response

{
  "tool": {
    "id": 1,
    "slug": "json-formatter",
    "name": "JSON Formatter",
    "description": "Format, validate, and prettify JSON data instantly.",
    "category": "Developer",
    "is_pro": false,
    "emoji": "🧰",
    "created_at": "2026-01-15T10:30:00.000000Z"
  }
}

Auth

Authentication endpoints

Authentication

Register

Create a user account and receive a Bearer token for authenticated API requests.

No auth required201 CreatedResponse: { user, token }

POST/api/auth/register

Headers

NameValueWhen

Content-Typeapplication/jsonRequired when sending JSON body

Acceptapplication/jsonRecommended for all requests

Request body

FieldTypeRequiredDescription

namestringRequiredDisplay name for the account.

emailstringRequiredUnique email address.

passwordstringRequiredAccount password.

password_confirmationstringRequiredMust match password.

curl

curl -X POST "https://toolblip-api-production.up.railway.app/api/auth/register" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "[email protected]",
    "password": "correct-horse-battery-staple",
    "password_confirmation": "correct-horse-battery-staple"
  }'

JSON response

{
  "user": {
    "id": 42,
    "name": "Jane Doe",
    "email": "[email protected]",
    "is_pro": false
  },
  "token": "1|exampleBearerToken"
}

Authentication

Login

Exchange an email and password for a Bearer token.

No auth required200 OKResponse: { user, token }

POST/api/auth/login

Headers

NameValueWhen

Content-Typeapplication/jsonRequired when sending JSON body

Acceptapplication/jsonRecommended for all requests

Request body

FieldTypeRequiredDescription

emailstringRequiredAccount email address.

passwordstringRequiredAccount password.

curl

curl -X POST "https://toolblip-api-production.up.railway.app/api/auth/login" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "correct-horse-battery-staple"
  }'

JSON response

{
  "user": {
    "id": 42,
    "name": "Jane Doe",
    "email": "[email protected]",
    "is_pro": false
  },
  "token": "2|exampleBearerToken"
}

Authentication

Logout

Revoke the current token. The token used for the request stops working immediately.

Bearer token required200 OKResponse: { message }

POST/api/auth/logout

Headers

NameValueWhen

AuthorizationBearer YOUR_TOKENRequired

Acceptapplication/jsonRecommended for all requests

curl

curl -X POST "https://toolblip-api-production.up.railway.app/api/auth/logout" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

JSON response

{
  "message": "Logged out successfully"
}

Authentication

Get authenticated user

Return the user profile attached to the supplied Bearer token.

Bearer token required200 OKResponse: { user }

GET/api/auth/user

Headers

NameValueWhen

AuthorizationBearer YOUR_TOKENRequired

Acceptapplication/jsonRecommended for all requests

curl

curl "https://toolblip-api-production.up.railway.app/api/auth/user" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

JSON response

{
  "user": {
    "id": 42,
    "name": "Jane Doe",
    "email": "[email protected]",
    "is_pro": false
  }
}

Errors

Errors are returned as JSON with a message. Validation errors may include an errors object keyed by field name.

Validation error

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}

Unauthorized

{
  "message": "Unauthenticated."
}

Common status codes

200 OK
201 Created
401 Missing or invalid token
404 Resource not found
422 Validation failed
500 Server error