Notion2API

The server provides a specialized streaming mechanism for the /v1/responses endpoint using a sequence of SSE events. This is more granular than the standard OpenAI chat completions stream.

Event Lifecycle:

• response.created: The response object is initialized.
• response.in_progress: Indicates the model is currently generating.
• response.output_item.added: An output item (like a message) is added to the response.
• response.content_part.added: A new content part is being processed.
• response.reasoning.delta: Incremental chunks of reasoning text.
• response.output_text.delta: Incremental chunks of visible text.
• response.reasoning.done: The reasoning phase has finished.
• response.output_text.done: The visible text generation is complete.
• response.output_item.done: The specific output item is finalized.
• response.completed: The entire response process is finished.

The following keys are the primary configuration options for Notion2API. Refer to config.example.json or config.docker.json for full schemas.

The PromptConfig interface allows fine-tuning of how the AI interacts with users and handles errors. You can define custom prefixes for different scenarios to guide the model's reasoning or retry logic.

Available configuration keys:

• profile: The default prompt profile to use.
• custom_prefix: A string to prepend to prompts.
• fallback_profiles: A list of profiles to use if the primary fails.
• max_escalation_steps: Limit for how many times the system attempts to resolve an issue.
• max_refusal_retries: Limit for retrying when the model refuses a prompt.
• cognitive_reframing_prefix: Prefix used for cognitive reframing tasks.
• toolbox_capability_expansion_prefix: Prefix for expanding tool capabilities.
• coding_retry_prefixes: Array of prefixes used specifically for coding retries.
• general_retry_prefixes: Array of prefixes for general retries.
• direct_answer_retry_prefixes: Array of prefixes for retries when a direct answer is expected.

You can deploy Notion2API using Docker Compose. The configuration is highly parameterized using environment variables, allowing you to customize the image name, container name, port mapping, volume mounts, and proxy settings without modifying the docker-compose.yml file directly.

Port Mapping

By default, the service listens on port 8787. You can change the host port using the N2A_PORT environment variable.

Volume Mounts

• Configuration: The application expects a configuration file at /app/config/config.json. You can map your local config file using N2A_CONFIG_FILE (defaults to ./config.docker.json). This is mounted as read-only (ro).
• Data Directory: Persistent data is stored in /app/data. You can map a local directory using N2A_DATA_DIR (defaults to ./data).

Proxy and Resin Settings

The service supports various proxy modes and Resin sticky proxy configurations via environment variables such as N2A_PROXY_MODE, N2A_PROXY_URL, and N2A_RESIN_ENABLED.

services:
  notion2api:
    image: ${N2A_IMAGE:-notion2api:latest}
    container_name: ${N2A_CONTAINER_NAME:-notion2api}
    ports:
      - "${N2A_PORT:-8787}:8787"
    volumes:
      - ${N2A_CONFIG_FILE:-./config.docker.json}:/app/config/config.json:ro
      - ${N2A_DATA_DIR:-./data}:/app/data
    environment:
      N2A_PROXY_MODE: ${N2A_PROXY_MODE:-}
      N2A_PROXY_URL: ${N2A_PROXY_URL:-}
      N2A_RESIN_ENABLED: ${N2A_RESIN_ENABLED:-}
      # ... other env vars

The AppConfigShape interface defines the core configuration for the Notion2API instance. This includes network settings, upstream proxy configurations, model management, and storage persistence.

Key configuration groups include:

• Network/Upstream: host, port, upstream_base_url, upstream_origin, and upstream_host_header.
• Models: default_model, model_id, and model_aliases (a mapping of aliases to actual model IDs).
• Storage: Configures SQLite usage and persistence for conversations, conversation_snapshots, responses, continuation_sessions, and sillytavern_bindings.
• Admin: Security settings including password and token_ttl_hours.
• Features: Toggles for web search, read-only mode, image generation, and CSV support.
• Prompt: Customization of AI behavior via PromptConfig (profiles, prefixes, and retry logic).

// Example of the AppConfigShape structure
const config: AppConfigShape = {
  host: 'localhost',
  port: 3000,
  default_model: 'gpt-4',
  storage: {
    sqlite_path: './data.db',
    persist_conversations: true
  },
  features: {
    use_web_search: true,
    enable_generate_image: false
  }
};