SWP Documentation & Guides

General Framework FREE

The General framework applies standard SWP tags suitable for any document type. It's the default framework and is available to all users, including free tier.

Best Use Cases

• Project Documentation: PRDs, specifications, requirements
• Personal Notes: Journals, idea logs, research notes
• Business Documents: Proposals, reports, presentations
• Creative Writing: Story outlines, character notes, world-building
• Technical Documentation: API docs, user guides, tutorials

Extended Optional Tags

Enable "Show Extended Tags" to access additional metadata options:

Example: Tagged Project Proposal

Framework Tags

These 8 metadata tags (including the mandatory @regulatory_scope) are automatically applied when using the Healthcare framework:

Best Use Cases

• Electronic Health Records (EHR): Patient record templates, clinical notes
• Clinical Decision Support: Treatment protocols, diagnostic workflows
• Healthcare Analytics: Population health reports, outcome tracking
• Telehealth Platforms: Virtual visit documentation, remote monitoring
• Medical Device Documentation: Device specs for FDA compliance

Example: Clinical Protocol Document

Framework Tags

These 8 safety-focused tags (including the mandatory @regulatory_scope) are automatically applied when using the Robotics framework:

Best Use Cases

• Autonomous Vehicles: Navigation specs, sensor fusion docs, safety cases
• Industrial Robotics: Manufacturing automation, collaborative robot specs
• Drone Systems: Flight control, obstacle avoidance, geofencing
• Medical Robotics: Surgical robot requirements, safety interlocks
• Warehouse Automation: AGV navigation, pick-and-place systems

Example: Autonomous Navigation Specification

Framework Tags

These 8 legal metadata tags (including the mandatory @regulatory_scope) are automatically applied when using the Legal framework:

Best Use Cases

• Contract Management: Agreement templates, clause libraries, amendments
• eDiscovery: Document review, privilege logging, production sets
• Compliance Documentation: Policy documents, regulatory filings
• Intellectual Property: Patent applications, trademark filings, IP portfolios
• Legal Research: Case analysis, precedent summaries, legal briefs

Example: Contract Template Document

Framework Tags

These 8 education metadata tags (including the mandatory @regulatory_scope) are automatically applied when using the Education framework:

Best Use Cases

• Learning Management Systems (LMS): Course structures, assignment specs, gradebook designs
• Curriculum Mapping: Standards alignment, lesson plans, scope and sequence
• Assessment Platforms: Test specifications, rubrics, adaptive learning algorithms
• Student Information Systems: Enrollment workflows, transcript management
• Educational Analytics: Learning outcome tracking, intervention triggers

Example: LMS Course Specification

Framework Tags

These 8 financial metadata tags (including the mandatory @regulatory_scope) are automatically applied when using the Finance framework:

Best Use Cases

• Account Statements: Monthly statements, transaction summaries, balance reports
• Transaction Processing: Payment workflows, transfer validation, settlement systems
• Risk Management: Risk assessments, exposure analysis, hedging strategies
• Regulatory Reporting: SOX compliance docs, FINRA filings, Basel III capital reports
• Portfolio Management: Investment strategies, asset allocation, performance tracking
• Compliance Automation: Policy enforcement, audit preparation, control monitoring
• Treasury Operations: Cash management, liquidity planning, funding strategies

Example: Account Statement

AI-Agent Workflows & Marketing Framework PRO

The AI-Agent Workflows framework provides structured tagging for multi-agent orchestration, task automation, and marketing workflows. This framework is designed for the web3 community, AI automation platforms, and autonomous systems where multiple agents collaborate on complex tasks.

Framework Tags

These 9 agent workflow tags (including the mandatory @regulatory_scope) are automatically applied when using the AI-Agent Workflows framework:

Best Use Cases

• Multi-Agent Orchestration: Coordinate multiple specialized AI agents in complex workflows
• Marketing Automation Pipelines: Structured email sequences, content calendars, campaign management
• Content Generation Workflows: Research, Draft, Edit, Publish chains with quality gates
• Lead Nurturing Sequences: Automated follow-up sequences with conditional branching
• Customer Support Bots: Ticket routing, response generation, escalation protocols
• Web3 DAO Automation: Governance proposals, voting workflows, treasury management
• Social Media Management: Cross-platform posting, engagement tracking, response automation
• Sales Funnel Automation: Lead qualification, outreach sequences, CRM integration

Extended Entity & Role Types

The Agent Workflow framework includes specialized types for multi-agent systems:

• Entity Types: agent, task, workflow, campaign, lead
• Role Types: orchestrator, executor, validator, reviewer, human_operator
• Document Types: prompt, template, response, log, report
• Domain Types: marketing, sales, support, content, web3

Example: Marketing Content Workflow

Official SDKs

IdeaPhase provides official client libraries for Python and JavaScript/TypeScript. Both SDKs wrap the full API with clean, idiomatic interfaces — encode documents, manage proofs, register webhooks, and share proofs between agents with just a few lines of code.

Python SDK

Installation

Quick Start

Batch Encoding

Proof Verification

Webhooks

Error Handling

Custom Base URL

JavaScript / TypeScript SDK

Installation

Quick Start

Batch Encoding

Proof Verification & Webhooks

TypeScript Types

The SDK exports full TypeScript type definitions for all API responses:

Error Handling

SDK → API Endpoint Mapping

SWP Ontology & Standards Crosswalks

The SWP ontology is a lightweight, layered description of the controlled vocabularies, is-a hierarchy, and relation types that sit on top of the tag generator. It is purely additive and read-only — it describes existing tags but never changes how a document is tagged. Everything here is fully deterministic: a fixed ontology version always produces byte-identical exports (no model calls, no clock, no randomness).

Three machine-readable exports

Each export is generated from a single source of truth (swp_ontology.py), so the published JSON can never silently drift from the live ontology.

Ontology JSON PROV-O crosswalk SKOS crosswalk FIBO crosswalk FHIR crosswalk LKIF crosswalk CORA crosswalk IEEE LOM crosswalk FIPA crosswalk

PROV-O: provenance alignment

PROV-O is the W3C standard for describing provenance — who produced what, from what, and when. SWP proofs map naturally onto its three core types:

• prov:Entity — the input document, the SWP-tagged output document, and the proof record.
• prov:Activity — the encoding event that consumed the input and generated the tagged output.
• prov:Agent — the API-key holder responsible for the encoding event.

The Stage 2 relation types map to PROV-O derivation/influence properties. Each mapping carries a precision flag so consumers know how faithful the alignment is:

exact = same meaning; broader = a more general PROV-O super-property; approximate = closest available property, semantics differ in nuance.

SKOS: vocabulary alignment

SKOS is the W3C standard for publishing controlled vocabularies and taxonomies. Each SWP facet becomes a skos:ConceptScheme, each term a skos:Concept, and the is-a hierarchy is expressed with skos:broader / skos:narrower. Root terms are marked as skos:hasTopConcept, and an emittable flag indicates which terms the encoder can actually output (abstract parent terms are non-emittable).

Domain crosswalks: every Pro framework

Beyond the cross-industry W3C standards above, the Pro domain frameworks carry sector-specific metadata and entity tags that align with recognized domain vocabularies. A deeper crosswalk maps each framework's tags onto its sector standard — all generated from domain_frameworks.py as the single source of truth, so they cannot silently drift:

• FIBO (Financial Industry Business Ontology) for the Finance framework — maps tags like @entity:account, @entity:customer, and @role:regulator onto FIBO concepts.
• FHIR (HL7 Fast Healthcare Interoperability Resources) for the Healthcare framework — maps tags like @audit_trail and @data_sensitivity onto FHIR resources (e.g. AuditEvent, Consent).
• LKIF-Core (Legal Knowledge Interchange Format) for the Legal framework — maps @regulatory_standards onto LKIF's Norm concept (with Akoma Ntoso referenced for document structure).
• IEEE 1872 CORA (Core Ontology for Robotics and Automation) for the Robotics framework — maps the sector and sensor/device tags onto CORA, with the ISO 13482 / IEC 61508 / ISO 26262 functional-safety standards referenced for the safety tags.
• IEEE LOM (Learning Object Metadata) for the Education framework — maps @content_standards onto LOM's Classification category and @data_sensitivity onto Ed-Fi student entities.
• FIPA (multi-agent system standards) for the AI-Agent Workflows framework — maps @entity:agent and the ACL-style message tags onto FIPA concepts; business/marketing tags (campaign, lead, web3) are honestly left unmapped.

Every domain tag is either mapped to a target concept with the same precision flag used by PROV-O (exact / broader / approximate) or explicitly marked unmapped with a reason — operational controls (audit posture, data minimization) that have no business-domain concept are honestly left unmapped rather than forced.

Each mapped entry now carries a pre-expanded iri_url — the namespace base joined to the local name — so you get a complete, clickable web address that resolves to the published concept without expanding the prefix yourself. The live crosswalk below renders each one as a direct link.

Live domain crosswalk

Pick a framework to load its committed crosswalk and see every tag mapped to its standard concept, with the full resolvable address:

SWP-Bus: Agent-to-Agent Mesh

The SWP-Bus is a lightweight neurosymbolic message bus built directly on top of the proof chain. Every published envelope is hashed, chained to its predecessor, and durably stored — so a stream of agent messages doubles as a tamper-evident audit log. Topics support fan-out subscriptions with HMAC-signed delivery; mesh sessions support 1:1 agent pairs over a shared, hash-chained transcript.

Endpoint Catalog (17)

Topics & Subscriptions

Mesh Sessions (1:1 agent pairs)

Dead Letter Queue

Topic Lifecycle

Create a topic, subscribe, publish envelopes, then pull or long-poll. Each published envelope is appended to the proof chain (proof_hash + prev_proof_hash), so consumers can verify continuity offline.

HMAC Verification Recipe

Messages delivered to a subscriber (pull or push) are signed with that subscription's plaintext secret and carry a non-null hmac_sha256 field. The signature covers the canonical JSON encoding of the message's envelope (sorted keys, compact separators). The plaintext secret is returned once at subscribe time — store it securely; the server only keeps a hash.

Messages pulled by the topic owner (or pulled from a mesh session) arrive with hmac_sha256: null and signed: false — those calls are already authenticated by the caller's own API key, so there is no shared secret to sign with. Every pull response also carries a top-level signed boolean so you can branch once per batch rather than per message.

Python (using the SDK)

JavaScript / TypeScript (using the SDK)

Verify in any language (canonical JSON)

Mesh Sessions

Mesh sessions are 1:1 channels for direct agent-to-agent conversation. Either side can publish; both pull from the same hash-chained transcript. Use sessions when two agents need to negotiate, hand off context, or co-author work without a public topic.

Replay & DLQ

Replay lets you re-read a slice of a topic — by offset range or by proof_hash with surrounding context — useful for debugging, audit, and disaster recovery. Push subscriptions that fail after retries land in the DLQ; you can inspect failures from the Pro Dashboard or via the API.

Dashboard & Status

The Pro Dashboard's SWP Bus tab gives you a live view of your topics, subscriptions, recent messages, mesh sessions, and DLQ entries, with one-click controls for create, delete, replay, and resolve. The public Status Page includes a SWP Bus component sourced from GET /api/health, so you can verify bus availability without an API key.

Response Codes & Presence-Oracle Policy

The bus endpoints use a deliberately uniform set of error codes so that an unauthorized caller cannot tell the difference between an object that does not exist and an object that exists but belongs to another tenant. This is a security guarantee — please code your clients against it.

Getting Started

The IdeaPhase SWP Encoding API lets you programmatically encode documents with Symbol Word Protocol tags. Every request returns structured, AI-readable output with prompt templates, LoRA fine-tuning guidance, and a cryptographic proof chain for verifiable document lineage.

Base URL

Prerequisites

1. Active Pro Subscription — Sign up at ideaphase.app and upgrade to Pro ($29.99/month)
2. API Key — Create one from the API Key Management section on the home page, or use the /api/v1/key/create endpoint

Quick Start (cURL)

Authentication

All API requests require a Bearer token in the Authorization header. Your API key starts with swp_ followed by a unique token.

Header Format

Authentication Errors

Encode Endpoint

The core endpoint that transforms raw text into SWP-tagged, AI-readable output.

POST /api/v1/encode

Request Body (JSON)

Example Request

Example Response (200 OK)

Response Fields Explained

Domain Frameworks

Pass a framework parameter to apply industry-specific metadata tags. Each framework adds regulatory and sector tags alongside the core SWP tags.

Example: Encoding with Finance Framework

API Key Management

Pro subscribers can create up to 5 API keys. Keys are prefixed with swp_ and stored as SHA-256 hashes — the full key is shown only at creation.

POST /api/v1/key/create

Create a new API key. Requires an active Pro session (cookie-based auth from the web app).

Request Body

Example Response (201 Created)

GET /api/v1/key/list

List all your API keys with usage statistics. Requires an active session.

Example Response (200 OK)

POST /api/v1/key/revoke

Permanently deactivate a compromised or unused key. Requires an active session.

Request Body

Example Response (200 OK)

POST /api/v1/key/rotate

Atomically revoke an old key and create a new one. Requires an active Pro session.

Request Body

Example Response (200 OK)

Proof Chain & Document Verification

Every document encoded through the API generates a SHA-256 cryptographic proof that chains to the previous proof for your API key. This creates a verifiable, tamper-proof record of every document you have encoded — without storing any raw content.

How the Proof Chain Works

1. You send a document to /api/v1/encode
2. IdeaPhase generates SHA-256 hashes of both the input and output
3. A combined proof_hash is created from input_hash + output_hash + timestamp
4. This proof is linked to your previous proof via previous_proof_hash, forming a chain
5. The response includes a proof object with the document_id, proof_hash, and chain position

Proof Object (included in every encode response)

GET /api/v1/proof/{document_id} AUTH

Download a full proof receipt for a specific document. Requires the API key that created the proof.

Example Request

Example Response (200 OK)

GET /api/v1/proof/verify/{proof_hash} PUBLIC

Verify that a proof exists and is valid. No authentication required — anyone can verify a proof hash.

Example Request

Example Response (200 OK)

GET /api/v1/proof/chain/{key_prefix}/verify PUBLIC

Verify the integrity of an entire proof chain for a given API key prefix. Detects broken links and tampered hashes.

Example Request

Example Response (200 OK)

Webhook Notifications

Pro users can register webhook URLs to receive real-time HTTP callbacks when events occur. Payloads are HMAC-signed with a per-webhook secret for tamper-proof verification.

Supported Events

POST /api/v1/webhooks AUTH

Register a new webhook endpoint.

Request Body

Response (201 Created)

GET /api/v1/webhooks AUTH

List all registered webhooks for your account. Each entry includes created_at and updated_at timestamps so you can see when the configuration was last changed.

Response (200 OK)

PATCH /api/v1/webhooks/{id} AUTH

Update a webhook's url, events, and/or is_active flag in place without rotating its signing secret. Provide at least one of the three fields. The new URL is re-validated against the same SSRF rules as registration; events are validated against the supported event list. Setting is_active to false pauses delivery (the row and secret are preserved); setting it back to true resumes delivery. On success, updated_at is bumped automatically.

Quota note: Reactivating a paused webhook counts against your active-webhook quota. If you are already at the limit, a PATCH that sets is_active: true on a currently paused row is rejected with 400 (same error message as registration). Pause or delete an active row first, then reactivate.

Response Codes

Request Body

Response (200 OK)

DELETE /api/v1/webhooks/{id} AUTH

Remove a webhook by ID.

Webhook Payload Format

Each webhook delivery includes an HMAC-SHA256 signature in the X-IdeaPhase-Signature header, formatted as sha256=<hex>. The event name is also sent in the X-IdeaPhase-Event header. Verify the signature using your webhook secret:

Verifying Webhook Signatures (Python)

Agent-to-Agent Proof Sharing

Enable cross-platform proof verification between different API keys. Agents can share proof receipts via time-limited tokens and create cross-reference links for multi-agent verification chains.

Sharing Workflow

1. Agent A encodes a document and gets a proof hash
2. Agent A calls /api/v1/proof/share to generate a shareable token
3. Agent A sends the share token to Agent B (via API, message queue, etc.)
4. Agent B calls /api/v1/proof/shared/{token} to verify the proof (public, no auth needed)
5. Agent B optionally calls /api/v1/proof/cross-reference to link their own proof to Agent A's proof

POST /api/v1/proof/share AUTH

Generate a time-limited, HMAC-signed share token for a specific proof.

Request Body

Response (200 OK)

GET /api/v1/proof/shared/{share_token} PUBLIC

Verify a shared proof using its token. No authentication required — anyone with the token can verify the proof. Only hashes and metadata are returned, never the original content.

Response (200 OK)

POST /api/v1/proof/cross-reference AUTH

Create a cross-reference link between your proof and a shared proof from another agent. This creates a verifiable connection between proofs across different API keys.

Request Body

Response (200 OK)

GET /api/v1/proof/cross-references/{proof_hash} AUTH

List all cross-references linked to a specific proof (both directions). You must own the proof — either as the original encoder (a row in your document_proofs) or as the source of an existing outbound cross-reference. Otherwise the endpoint returns a uniform 404.

Response Codes

V2 API Endpoints

The V2 API provides an enhanced response format with request IDs, rate limit headers, and structured error codes. V1 remains the stable, backward-compatible version and is not deprecated.

V2 Response Enhancements

POST /api/v2/encode AUTH

Same input as V1. Enhanced response with version metadata and rate limit info.

Request

Response Headers

Response Body (200 OK)

POST /api/v2/encode/batch AUTH

Same input as V1 batch. Enhanced response format with V2 metadata.

GET /api/v2/proof/verify/{proof_hash} PUBLIC

Verify a proof with V2 structured response format.

V2 Error Response Format

Version Negotiation on V1 Endpoints

If you want V2 response format but want to keep using V1 URLs, add the Accept-Version: v2 header:

Rate Limits & Quotas

API access is rate-limited to ensure fair usage across all clients.

Rate Limit Response (429)

V2 Rate Limit Headers

V2 endpoints (and V1 endpoints with Accept-Version: v2) include rate limit information in the response headers:

Use these headers to implement client-side throttling and avoid hitting 429 errors.

Error Reference

All errors return JSON with an error field. Common HTTP status codes:

Example Error Responses

Security & Metadata

Key Security

• SHA-256 Hashed Storage: API keys are hashed before storage. IdeaPhase cannot recover your key — store it securely at creation.
• Key Prefix Identification: Each key has a visible prefix (e.g., swp_a1b2) for identification without exposing the full key.
• Instant Revocation: Compromised keys can be revoked immediately via the web UI or API.
• Key Rotation: Atomically replace a key without downtime — old key is revoked and new one is issued in a single operation.

Data Privacy

• No Content Storage: Your document content is processed in memory and never persisted to the database.
• Hash-Only Proofs: The proof chain stores only SHA-256 hashes (input_hash, output_hash, proof_hash) — never raw content.
• GDPR/HIPAA Compliant: Hash-only architecture means no personally identifiable information or protected health information is stored.
• HTTPS Only: All API traffic is encrypted in transit via TLS.

Audit Trail

• Full Request Logging: Every API request is logged with timestamp, key prefix, endpoint, status code, and processing time.
• Proof Chain Integrity: Tamper detection via chained SHA-256 hashes — any modification breaks the chain and is detectable.
• Usage Tracking: Per-key daily and total request counts for monitoring and accountability.

Health & Discovery

Public endpoints for monitoring system health and discovering available API endpoints. No authentication required.

GET /api/health

Returns real-time system health with per-component status. Use this for uptime monitoring, load balancer health checks, or integration readiness verification. Returns HTTP 200 when healthy or degraded, HTTP 503 when unhealthy.

Authentication: None — Rate Limit: 30 requests/minute

Example Request

Example Response (200 OK)

Status Values

GET /api/v1/discovery

Returns a complete, machine-readable catalog of all available API endpoints grouped by category. Useful for automated API client generation, documentation tools, or integration bootstrapping.

Authentication: None — Rate Limit: 10 requests/minute

Example Request

Example Response (200 OK)

GET /docs (Redirect)

Convenience redirect (HTTP 301) to /swp-docs. Provides a standard documentation shortcut for developers who expect to find API docs at /docs.

Authentication: None — Response: 301 Moved Permanently with Location: /swp-docs

Need Help?

IdeaPhase provides multiple support channels:

• AI Support Chat: Get instant answers about SWP protocol, API usage, and troubleshooting at /support. Powered by GPT-4o with deep knowledge of the SWP platform. Available to all visitors, no login required.
• System Status: Check real-time platform health at /status or programmatically via GET /api/health.
• Email: ideaphase.needs@gmail.com for account-specific issues or partnership inquiries.

Integration Examples

Python

JavaScript (Node.js)

cURL — Full Workflow

Integration Guide: SWP + Your Local LLM

This guide walks you through the complete workflow of using the SWP Encoding API with local language models like Ollama, LM Studio, or other Agent frameworks.

How the Flow Works

1. Send your raw text to the IdeaPhase /api/v1/encode endpoint with your API key
2. Receive back: SWP-tagged document + prompt template + LoRA fine-tuning guidance + cryptographic proof
3. Take the prompt_template from the response and send it to your local LLM
4. The LLM reads the SWP tags and produces structured, metadata-aware output

Quick Start with Official SDKs (Recommended)

The fastest way to integrate SWP into your application is with the official SDKs. They handle authentication, error handling, and response parsing for you.

Python: Full Encode → Verify Workflow

JavaScript/TypeScript: Full Encode → Verify Workflow

Integration with Raw HTTP (cURL, requests, fetch)

If you prefer direct HTTP calls without an SDK, follow the steps below.

Step 0: Test Your API Key

Before encoding, verify your key works with this simple test endpoint. It tells you exactly what the server received, helping you catch quoting issues.

Linux / Mac / Git Bash

Windows CMD (one line)

Windows PowerShell

Step 1: Encode with cURL

Choose your platform below. The commands do the same thing — the only difference is how each terminal handles quotes.

Linux / Mac / Git Bash

Windows CMD

Inner quotes in the JSON body are escaped with \".

Windows PowerShell

Use curl.exe with the --% stop-parsing token. This tells PowerShell to pass everything after it directly to curl without any interpretation:

All three commands return a JSON response. The prompt_template field contains the complete prompt ready for your LLM.

Send to Ollama (all platforms)

Linux / Mac / Git Bash:

Windows CMD:

Windows PowerShell:

Python Integration

A complete Python script showing the full workflow:

Ollama Setup

Ollama runs open-source models locally on your machine. It has a simple REST API that works perfectly with SWP.

1. Install Ollama from ollama.ai
2. Pull a model: ollama pull llama3
3. Start the server: ollama serve (runs on port 11434)
4. Use the Python script above or the downloaded integration script

LM Studio Setup

LM Studio provides a GUI for running local models with an OpenAI-compatible API server.

1. Download from lmstudio.ai
2. Search and download any GGUF model (Llama 3, Mistral, etc.)
3. Go to the "Local Server" tab and click "Start Server" (runs on port 1234)
4. LM Studio exposes an OpenAI-compatible API — use the /v1/chat/completions endpoint

Agent Frameworks

For agent frameworks, the SWP API call happens from within your agent's tool or action definition. The key insight: SWP is a pre-processing step that runs before your agent sends text to its LLM.

Integration Pattern for Agent Frameworks

Any OpenAI-Compatible Endpoint

SWP works with any system that accepts text prompts. If your tool uses the OpenAI API format (most do), use this pattern:

What You Get Back from the API

Every encode call returns these key fields:

Founder Key vs. Pro Key

Verifying Proofs

Every encoded document gets a cryptographic proof. You can verify proofs publicly without authentication:

This is how you prove a document existed at a specific time and hasn't been tampered with — critical for regulated industries.

Production Deployment Guide

This guide covers deploying SWP-tagged applications and integrating IdeaPhase into your production systems.

Frequently Asked Questions

API Integration

IdeaPhase provides a full REST API for programmatic SWP encoding, key management, and cryptographic proof verification. Pro subscribers can create API keys and start encoding immediately.

• REST API: Full documentation with input/output examples in the API Reference tab
• Proof Chain: Every API-encoded document gets a verifiable cryptographic proof with chain integrity
• Code Examples: Python, JavaScript, and cURL examples ready to copy and use
• 7 Domain Frameworks: Healthcare, Robotics, Legal, Education, Finance, AI-Agents, and General

For enterprise needs (custom rate limits, SLA guarantees, custom frameworks), contact ideaphase.needs@gmail.com.

Security Considerations

• Data Privacy: Documents are processed but not stored permanently. Only proof hashes are retained.
• HTTPS Only: All traffic is encrypted in transit.
• No Third-Party Sharing: Your content is never shared with external parties.
• Metadata Ready: Framework tags indicate but don't enforce compliance; implement appropriate controls in your systems.