Intertext API Guide

A minimal, complete guide to using the Intertext API for programmatic queries.

Quick Start

Get an API token via Signal/SMS: Send generate api token
Make a request: curl "https://api.example.com/api/v1/query?token=YOUR_TOKEN&q=time"
Done!

Getting Your API Token

Send a Signal or SMS message to your Intertext number:

generate api token

You’ll receive a response with your API token. Save this token - you’ll need it for all API requests.

Note: Generating a new token automatically revokes your previous token. Only one token is active per user.

Making Requests

Method 1: GET (Simple, Retro-Friendly)

Perfect for retro computers, simple HTTP clients, or quick testing.

curl "https://api.example.com/api/v1/query?token=YOUR_TOKEN&q=weather"

Parameters:

token (required) - Your API token
q (required) - Your query text
text_mode (optional) - Response format: compact, normal, verbose, or vintage
linewidth (optional) - Line width for vintage mode (40-200 columns)

Method 2: POST (Modern, Secure)

Recommended for modern applications and security-conscious clients.

curl -X POST https://api.example.com/api/v1/query \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "weather"}'

Headers:

Authorization: Bearer YOUR_TOKEN (required)
Content-Type: application/json (required)

JSON Body:

{
  "query": "weather",
  "text_mode": "vintage",
  "linewidth": 80
}

Response Formats

Plain Text (Default)

Simple text response, perfect for terminals and retro computers.

curl "https://api.example.com/api/v1/query?token=abc123&q=time"

Response:

The current time is 14:30 UTC (15:30 CET)

JSON (Modern Apps)

Add Accept: application/json header for structured responses.

curl -H "Accept: application/json" \
  "https://api.example.com/api/v1/query?token=abc123&q=time"

Response:

{
  "success": true,
  "response": "The current time is 14:30 UTC (15:30 CET)",
  "timestamp": "2026-01-11T14:30:00Z"
}

Available Services

All services available via Signal/SMS work through the API:

Time: time, time in Tokyo, timezone Stockholm
Weather: weather, weather in Paris
News: news, news world, news business
Settings: settings, set locale sv_SE, set temp_unit F
Help: help, commands, info, manual

Premium services (pollen, navigation, nearby) require a paid account plan.

Text Modes

Control response formatting with the text_mode parameter:

Normal Mode (Default)

Standard formatting with Unicode characters.

curl "https://api.example.com/api/v1/query?token=abc123&q=weather"

Response:

Current weather: 5°C, Partly cloudy
Wind: 12 km/h SE • Humidity: 65%

Vintage Mode (ASCII-Only)

For retro terminals (VT100, ADM-3A, Commodore 64, Apple II).

curl "https://api.example.com/api/v1/query?token=abc123&q=weather&text_mode=vintage&linewidth=40"

Response:

Current weather: 5C, Partly cloudy
Wind: 12 km/h SE - Humidity: 65%

Features:

ASCII-only output (7-bit, no Unicode)
Configurable line width (40-200 columns)
Word-boundary wrapping
Compatible with classic terminals

Common Line Widths:

40 - Commodore VIC-20, early terminals
80 - VT100, most classic terminals (default)
132 - VT100 wide mode, modern terminals

Compact Mode

Minimal output, perfect for bandwidth-constrained connections.

curl "https://api.example.com/api/v1/query?token=abc123&q=weather&text_mode=compact"

Verbose Mode

Detailed output with additional information.

curl "https://api.example.com/api/v1/query?token=abc123&q=weather&text_mode=verbose"

Implementation Examples

Shell Script (POSIX)

#!/bin/sh
TOKEN="your_token_here"
QUERY="$1"

curl -s "https://api.example.com/api/v1/query?token=${TOKEN}&q=${QUERY}"

Usage: ./hal.sh "weather"

Python

import requests

TOKEN = "your_token_here"

def query_hal(query, text_mode=None, linewidth=None):
    params = {"token": TOKEN, "q": query}
    if text_mode:
        params["text_mode"] = text_mode
    if linewidth:
        params["linewidth"] = linewidth

    response = requests.get(
        "https://api.example.com/api/v1/query",
        params=params
    )
    return response.text

# Example usage
print(query_hal("time"))
print(query_hal("weather", text_mode="vintage", linewidth=40))

JavaScript (Node.js)

const axios = require('axios');

const TOKEN = 'your_token_here';

async function queryHal(query, options = {}) {
  const params = new URLSearchParams({
    token: TOKEN,
    q: query,
    ...options
  });

  const response = await axios.get(
    `https://api.example.com/api/v1/query?${params}`
  );
  return response.data;
}

// Example usage
queryHal('time').then(console.log);
queryHal('weather', { text_mode: 'vintage', linewidth: 80 })
  .then(console.log);

Retro BASIC (Commodore 64, Apple II)

10 REM Intertext API CLIENT
20 TOKEN$ = "your_token_here"
30 INPUT "QUERY: "; Q$
40 URL$ = "https://api.example.com/api/v1/query"
50 URL$ = URL$ + "?token=" + TOKEN$
60 URL$ = URL$ + "&q=" + Q$
70 URL$ = URL$ + "&text_mode=vintage&linewidth=40"
80 REM Use your platform's HTTP library here
90 PRINT RESPONSE$

cURL One-Liners

# Simple query
curl "https://api.example.com/api/v1/query?token=abc123&q=time"

# Vintage mode for VT100
curl "https://api.example.com/api/v1/query?token=abc123&q=weather&text_mode=vintage&linewidth=80"

# JSON response
curl -H "Accept: application/json" \
  "https://api.example.com/api/v1/query?token=abc123&q=news"

# POST request
curl -X POST https://api.example.com/api/v1/query \
  -H "Authorization: Bearer abc123" \
  -H "Content-Type: application/json" \
  -d '{"query": "weather"}'

Error Handling

Authentication Errors

Missing Token:

ERROR: Missing API token. Provide via ?token= or Authorization: Bearer header

Invalid Token:

ERROR: Invalid or revoked API token

Request Errors

Missing Query:

ERROR: Missing query parameter. Provide via ?q= or JSON body

Service Error:

ERROR: Service error: [detailed message]

JSON Error Format

With Accept: application/json:

{
  "success": false,
  "error": "Invalid or revoked API token",
  "timestamp": "2026-01-11T14:30:00Z"
}

Rate Limiting & Usage

No explicit rate limits currently enforced
Usage tracked per token for monitoring
Fair use policy applies
Premium services require paid account plan

Security Best Practices

Keep your token secret - Treat it like a password
Use HTTPS - Never send tokens over HTTP
Use POST + Bearer header for production apps (keeps token out of URL)
Regenerate token if compromised - Send generate api token to get a new one
Don’t commit tokens to version control

Troubleshooting

“Invalid token” after generating new token

Only the most recent token is valid. Generating a new token revokes all previous tokens.

Response is empty

Check that your query is properly URL-encoded. Spaces should be %20 or +.

# Bad
curl "https://api.example.com/api/v1/query?token=abc&q=weather in Paris"

# Good
curl "https://api.example.com/api/v1/query?token=abc&q=weather+in+Paris"

Connection timeout

The API has a 30-second timeout. Most queries complete in under 2 seconds.

LLM Integration

This API is designed to be easily integrated by LLMs and AI assistants.

Minimal Implementation Prompt

You are integrating with the Intertext API at https://api.example.com/api/v1/query

To make a request:
1. Use GET method
2. Add query parameter: token=USER_TOKEN
3. Add query parameter: q=USER_QUERY
4. Optional: text_mode=vintage&linewidth=80 for ASCII-only output

Example: https://api.example.com/api/v1/query?token=abc123&q=time

Response is plain text by default, or JSON if Accept: application/json header is sent.

Tool/Function Definition (OpenAI Format)

{
  "name": "query_hal",
  "description": "Query the Intertext API for time, weather, news, and other services",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The query to send to Intertext (e.g., 'time', 'weather', 'news')"
      },
      "text_mode": {
        "type": "string",
        "enum": ["compact", "normal", "verbose", "vintage"],
        "description": "Response format. Use 'vintage' for ASCII-only output"
      },
      "linewidth": {
        "type": "integer",
        "minimum": 40,
        "maximum": 200,
        "description": "Line width for vintage mode (40-200 columns)"
      }
    },
    "required": ["query"]
  }
}

Platform-Specific Notes

Commodore 64 / VIC-20

Use text_mode=vintage&linewidth=40 for VIC-20 (40 columns)
Use text_mode=vintage&linewidth=80 for C64 (40 or 80 column mode)
Recommended: ML-based HTTP client or WiFi cartridge

Apple II

Use text_mode=vintage&linewidth=40 for 40-column displays
Use text_mode=vintage&linewidth=80 for 80-column cards
Recommended: Uthernet II or similar networking hardware

VT100 Terminals

Use text_mode=vintage&linewidth=80 for standard mode
Use text_mode=vintage&linewidth=132 for wide mode
Output is 7-bit ASCII compatible

Modern Terminals

Default text_mode=normal provides best experience
Unicode support for weather symbols, arrows, etc.
No line width restrictions

API Reference Summary

Endpoint

GET/POST https://api.example.com/api/v1/query

Authentication

GET: ?token=YOUR_TOKEN
POST: Authorization: Bearer YOUR_TOKEN

Parameters

Parameter	Type	Required	Default	Description
`token`	string	Yes (GET)	-	Your API token
`q` / `query`	string	Yes	-	Query text
`text_mode`	string	No	`normal`	Response format: `compact`, `normal`, `verbose`, `vintage`
`linewidth`	integer	No	`80`	Line width for vintage mode (40-200)

Headers

Header	Required	Description
`Authorization`	POST only	Bearer token authentication
`Content-Type`	POST only	Must be `application/json`
`Accept`	No	Set to `application/json` for JSON responses

Response Codes

Code	Meaning
200	Success
400	Bad request (missing query)
401	Unauthorized (invalid/missing token)
500	Internal server error

Support

For issues or questions:

Check your Intertext account plan (some services require paid plans)
Verify token is current (regenerate if needed)
Review query syntax in the main Intertext manual: Send manual via Signal/SMS

Last Updated: 2026-01-11 API Version: v1 Base URL: https://api.example.com/api/v1/