External API Documentation

This API allows you to programmatically manage trades and tables.

Configuration

Add EXTERNAL_API_KEY to your .env file:

EXTERNAL_API_KEY=your-secure-secret-key-here

Authentication

Auth Header: x-api-key: <your-secure-secret-key-here> (Required for all endpoints)

Tables

Create Table

URL: /api/external/tables Method: POST

Payload

Field	Type	Required	Description
`userId`	string	Yes	The ID of the user owning the table.
`name`	string	Yes	Name of the table.

Example Request (cURL)

curl -X POST https://journals.trading/api/external/tables \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-key" \
  -d '{
    "userId": "user_123",
    "name": "Bot Trades 2023"
  }'

Get User Tables

URL: /api/external/tables Method: GET

Query Parameters

Parameter	Required	Description
`userId`	Yes	The ID of the user to fetch tables for.

Example Request (cURL)

curl "https://journals.trading/api/external/tables?userId=user_123" \
  -H "x-api-key: your-key"

Update Table

URL: /api/external/tables Method: PATCH

Payload

Field	Type	Required	Description
`id`	number	Yes	The ID of the table to update.
`userId`	string	Yes	The ID of the user (for ownership verification).
`name`	string	Yes	New name for the table.

Example Request (cURL)

curl -X PATCH https://journals.trading/api/external/tables \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-key" \
  -d '{
    "id": 10,
    "userId": "user_123",
    "name": "Renamed Table"
  }'

Delete Table

URL: /api/external/tables Method: DELETE

Payload

Field	Type	Required	Description
`id`	number	Yes	The ID of the table to delete.
`userId`	string	Yes	The ID of the user (for ownership verification).

Example Request (cURL)

curl -X DELETE https://journals.trading/api/external/tables \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-key" \
  -d '{
    "id": 10,
    "userId": "user_123"
  }'

Trades

Create Trade

URL: /api/external/trades Method: POST

Payload

Field	Type	Required	Description
`userId`	string	Yes	The ID of the user the trade belongs to.
`asset`	string	Yes	Name of the asset (e.g., "BTC", "AAPL").
`entryPrice`	number	Yes	Entry price.
`exitPrice`	number	Yes	Exit price.
`longOrShort`	"long" \| "short"	No	Default is "long".
`entryDate`	string (ISO)	No	Date of entry.
`exitDate`	string (ISO)	No	Date of exit.
`resultComment`	string	No	Comment or notes.
`tableId`	number	No	ID of an existing table to link this trade to.

Note: If tableId is provided, the system verifies it exists for that user before creating the trade.

Example Request (cURL)

curl -X POST https://journals.trading/api/external/trades \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-key" \
  -d '{
    "userId": "user_123",
    "asset": "ETH",
    "longOrShort": "long",
    "entryPrice": 2000,
    "exitPrice": 2100,
    "tableId": 10
  }'

Update Trade

URL: /api/external/trades Method: PATCH

Payload

Field	Type	Required	Description
`id`	number	Yes	The ID of the trade to update.
`userId`	string	Yes	The ID of the user (for ownership verification).
`asset`	string	No	Name of the asset.
`entryPrice`	number	No	Entry price.
`exitPrice`	number	No	Exit price.
`longOrShort`	"long" \| "short"	No	Direction.
`entryDate`	string (ISO)	No	Date of entry.
`exitDate`	string (ISO)	No	Date of exit.
`resultComment`	string	No	Comment or notes.

Delete Trade

URL: /api/external/trades Method: DELETE

Payload

Field	Type	Required	Description
`id`	number	Yes	The ID of the trade to delete.
`userId`	string	Yes	The ID of the user (for ownership verification).

Example Request (cURL)

curl -X DELETE https://journals.trading/api/external/trades \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-key" \
  -d '{
    "id": 123,
    "userId": "user_123"
  }'

Get Trades

URL: /api/external/trades Method: GET

Query Parameters

Parameter	Required	Description
`userId`	Yes	The ID of the user to fetch trades for.
`tableId`	No	If provided, fetches trades only for this specific table.
`limit`	No	Max number of trades to return (default: 50).

Example Request (cURL)

curl "https://journals.trading/api/external/trades?userId=user_123&limit=10" \
  -H "x-api-key: your-key"