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.
Prerequisite: Both SDKs require a Pro API key. Create one from the API Key Management section on the main page (requires an active Pro subscription).
Python SDK
Installation
pip install ideaphase
Quick Start
from ideaphase import IdeaPhase
client = IdeaPhase(api_key="swp_your_api_key_here")
result = client.encode(
"Design a patient intake system for emergency departments.",
framework="healthcare"
)
print(result["tagged_document"]["full_text"])
print(f"Proof hash: {result['proof']['proof_hash']}")
print(f"Chain position: {result['proof']['chain_position']}")
Batch Encoding
batch_result = client.encode_batch([
{"text": "Patient vital signs monitoring protocol.", "framework": "healthcare"},
{"text": "Autonomous drone navigation safety spec.", "framework": "robotics"},
{"text": "Software licensing agreement template.", "framework": "legal"}
])
for item in batch_result["results"]:
print(f"Framework: {item['metadata']['framework']}")
print(f"Proof: {item['proof']['proof_hash']}")
Proof Verification
verification = client.verify_proof("a1b2c3d4e5f6...64_char_hex...")
print(f"Valid: {verification['verified']}")
chain = client.verify_chain("swp_a1b2")
print(f"Chain valid: {chain['valid']}, Length: {chain['chain_length']}")
receipt = client.get_proof("d4e5f6a7-b8c9-1234-5678-9abcdef01234")
print(f"Receipt type: {receipt['receipt_type']}")
Webhooks
webhook = client.webhooks.create(
url="https://your-app.com/webhooks/swp",
events=["proof.created", "chain.verified"]
)
print(f"Webhook ID: {webhook['id']}")
print(f"Secret: {webhook['secret']}")
webhooks = client.webhooks.list()
client.webhooks.delete(webhook["id"])
Error Handling
from ideaphase import IdeaPhase, AuthenticationError, RateLimitError, IdeaPhaseError
client = IdeaPhase(api_key="swp_your_key")
try:
result = client.encode("Your text here")
except AuthenticationError:
print("Invalid or expired API key")
except RateLimitError:
print("Rate limit exceeded - wait and retry")
except IdeaPhaseError as e:
print(f"API error: {e}")
Custom Base URL
client = IdeaPhase(
api_key="swp_your_key",
base_url="https://your-ideaphase-instance.com",
timeout=60
)
JavaScript / TypeScript SDK
Installation
npm install ideaphase
Quick Start
import { IdeaPhase } from "ideaphase";
const client = new IdeaPhase({ apiKey: "swp_your_api_key_here" });
const result = await client.encode(
"Deploy autonomous navigation module v2.3 with LIDAR failover.",
{ framework: "robotics" }
);
console.log(result.tagged_document.full_text);
console.log(`Proof: ${result.proof.proof_hash}`);
console.log(`Chain #${result.proof.chain_position}`);
Batch Encoding
const batchResult = await client.encodeBatch([
{ text: "Patient vital signs monitoring protocol.", framework: "healthcare" },
{ text: "Q3 portfolio rebalancing required.", framework: "finance" },
{ text: "Contract clause amendment for Section 4.2.", framework: "legal" }
]);
for (const item of batchResult.results) {
console.log(`Framework: ${item.metadata.framework}`);
console.log(`Proof: ${item.proof.proof_hash}`);
}
Proof Verification & Webhooks
const verification = await client.verifyProof("a1b2c3d4e5f6...");
console.log(`Valid: ${verification.verified}`);
const chain = await client.verifyChain("swp_a1b2");
console.log(`Chain valid: ${chain.valid}, Length: ${chain.chain_length}`);
const webhook = await client.webhooks.create(
"https://your-app.com/webhooks/swp",
["proof.created", "proof.shared"]
);
console.log(`Secret: ${webhook.secret}`);
TypeScript Types
The SDK exports full TypeScript type definitions for all API responses:
import type {
EncodeResponse,
BatchEncodeResponse,
ProofVerifyResponse,
ChainVerifyResponse,
ProofReceipt,
Webhook
} from "ideaphase";
const result: EncodeResponse = await client.encode("Your text");
const tags = result.tagged_document.core_tags;
Error Handling
import { IdeaPhase, AuthenticationError, RateLimitError, IdeaPhaseError } from "ideaphase";
try {
const result = await client.encode("Your text here");
} catch (error) {
if (error instanceof AuthenticationError) {
console.error("Invalid or expired API key");
} else if (error instanceof RateLimitError) {
console.error("Rate limit exceeded - wait and retry");
} else if (error instanceof IdeaPhaseError) {
console.error(`API error (${error.statusCode}): ${error.message}`);
}
}
SDK → API Endpoint Mapping
Source Code: Python SDK is in sdk/python/ and JavaScript/TypeScript SDK is in sdk/js/. Both use the same API endpoints and authentication scheme (Bearer token).
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
https://ideaphase.app
Quick Access: You can reach this documentation at either /swp-docs or /docs (which redirects here). For a machine-readable catalog of all available endpoints, see GET /api/v1/discovery.
Prerequisites
- Active Pro Subscription — Sign up at ideaphase.app and upgrade to Pro ($29.99/month)
- API Key — Create one from the API Key Management section on the home page, or use the
/api/v1/key/create endpoint
Important: Your full API key is shown only once at creation. Store it securely — IdeaPhase stores only a SHA-256 hash and cannot recover your key.
Quick Start (cURL)
curl -X POST https://ideaphase.app/api/v1/encode \
-H "Authorization: Bearer swp_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"text": "Our AI assistant must respond within 200ms and fall back to cached responses if the primary model is unavailable.",
"framework": "general"
}'
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
Authorization: Bearer swp_your_api_key_here
Authentication Errors
{
"error": "Missing or invalid Authorization header. Use: Bearer <your_api_key>"
}
{
"error": "Invalid API key"
}
{
"error": "Daily API limit exceeded",
"limit": 100
}
Encode Endpoint
The core endpoint that transforms raw text into SWP-tagged, AI-readable output.
POST /api/v1/encode
Request Body (JSON)
Example Request
curl -X POST https://ideaphase.app/api/v1/encode \
-H "Authorization: Bearer swp_abc123..." \
-H "Content-Type: application/json" \
-d '{
"text": "The patient presents with elevated troponin levels indicating possible myocardial infarction. Immediate cardiac catheterization is recommended per ACC/AHA guidelines.",
"framework": "healthcare",
"include_extended_tags": true
}'
Example Response (200 OK)
{
"swp_version": "1.0",
"encoding_id": "a3f8b2c1e9d04712",
"tagged_document": {
"full_text": "@phase: Execution\n@weight: 0.92\n@symbolic_id: SWP-EXE-001\n@swp_sum: Clinical assessment...\n@sector: Healthcare\n@regulatory_standards: HIPAA, HITECH\n@compliance_posture: Active\n@data_sensitivity: PHI\n@audit_trail: Required\n@data_minimization: Applied\n@operational_principles: Patient Safety First\n\nThe patient presents with...",
"core_tags": {
"phase": "Execution",
"weight": 0.92,
"symbolic_id": "SWP-EXE-001",
"swp_sum": "Clinical assessment with cardiac emergency protocol..."
},
"extended_tags": {
"priority": "critical",
"confidence": "high",
"source_type": "clinical_note"
},
"domain_tags": {
"sector": "Healthcare",
"regulatory_standards": "HIPAA, HITECH",
"compliance_posture": "Active",
"data_sensitivity": "PHI",
"audit_trail": "Required",
"data_minimization": "Applied",
"operational_principles": "Patient Safety First"
}
},
"prompt_template": "You are processing an SWP-tagged document. Read the @phase and @weight tags first to understand priority and classification. The @symbolic_id provides a unique reference. Process the content according to the indicated phase and regulatory framework...",
"lora_guidance": {
"task_type": "classification_and_tagging",
"recommended_base_model": "llama-3-8b or mistral-7b",
"training_format": "instruction_following",
"suggested_hyperparameters": { ... }
},
"proof": {
"document_id": "d4e5f6a7-b8c9-1234-5678-9abcdef01234",
"proof_hash": "a1b2c3d4e5f6...64-char-sha256-hex...",
"chain_position": 7,
"previous_proof_hash": "f9e8d7c6b5a4...previous-sha256-hex...",
"timestamp": "2026-02-16T14:32:01+00:00",
"receipt_url": "/api/v1/proof/d4e5f6a7-b8c9-1234-5678-9abcdef01234"
},
"metadata": {
"processing_time_ms": 12.45,
"tag_count": 14,
"framework": "healthcare",
"input_length": 198,
"word_count": 24,
"input_hash": "c7d8e9f0a1b2...64-char-sha256-hex...",
"encoded_at": "2026-02-16T14:32:01+00:00"
}
}
Response Fields Explained
Domain Frameworks
Pass a framework parameter to apply industry-specific compliance tags. Each framework adds regulatory and sector tags alongside the core SWP tags.
Example: Encoding with Finance Framework
curl -X POST https://ideaphase.app/api/v1/encode \
-H "Authorization: Bearer swp_abc123..." \
-H "Content-Type: application/json" \
-d '{
"text": "Q3 portfolio rebalancing required. Client exposure to emerging markets exceeds 15% allocation target. Recommend gradual reduction over 30-day window to minimize market impact.",
"framework": "finance"
}'
"domain_tags": {
"sector": "Financial Services",
"regulatory_standards": "SOX, FINRA, Basel III, PCI-DSS",
"compliance_posture": "Active",
"data_sensitivity": "Confidential",
"audit_trail": "Required",
"risk_classification": "Medium",
"operational_principles": "Fiduciary Duty, Regulatory Compliance"
}
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)
{
"api_key": "swp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"key_id": 42,
"prefix": "swp_a1b2",
"label": "Production Key",
"created_at": "2026-02-16T14:00:00+00:00",
"rate_limit_per_minute": 10,
"daily_limit": 100,
"note": "Store this key securely. It cannot be retrieved again."
}
GET /api/v1/key/list
List all your API keys with usage statistics. Requires an active session.
Example Response (200 OK)
{
"keys": [
{
"id": 42,
"prefix": "swp_a1b2",
"label": "Production Key",
"is_active": true,
"requests_today": 23,
"requests_total": 1547,
"daily_limit": 100,
"rate_limit_per_minute": 10,
"last_used_at": "2026-02-16T13:45:22+00:00",
"created_at": "2026-01-15T09:00:00+00:00"
}
]
}
POST /api/v1/key/revoke
Permanently deactivate a compromised or unused key. Requires an active session.
Request Body
{
"key_id": 42
}
Example Response (200 OK)
{
"prefix": "swp_a1b2",
"revoked": true
}
POST /api/v1/key/rotate
Atomically revoke an old key and create a new one. Requires an active Pro session.
Request Body
{
"key_id": 42,
"label": "Rotated Production Key"
}
Example Response (200 OK)
{
"api_key": "swp_x9y8z7w6v5u4t3s2r1q0...",
"key_id": 43,
"prefix": "swp_x9y8",
"label": "Rotated Production Key",
"old_prefix": "swp_a1b2",
"created_at": "2026-02-16T15:00:00+00:00",
"note": "Old key has been revoked. Store the new key securely."
}
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.
Privacy by Design: IdeaPhase stores only SHA-256 hashes of your input and output — never the actual document content. This makes the proof chain GDPR and HIPAA compliant while still providing strong evidence of document existence and processing time.
How the Proof Chain Works
- You send a document to
/api/v1/encode
- IdeaPhase generates SHA-256 hashes of both the input and output
- A combined
proof_hash is created from input_hash + output_hash + timestamp
- This proof is linked to your previous proof via
previous_proof_hash, forming a chain
- The response includes a
proof object with the document_id, proof_hash, and chain position
Proof Object (included in every encode response)
"proof": {
"document_id": "d4e5f6a7-b8c9-1234-5678-9abcdef01234",
"proof_hash": "a1b2c3d4e5f6...",
"chain_position": 7,
"previous_proof_hash": "f9e8d7c6b5a4...",
"timestamp": "2026-02-16T14:32:01+00:00",
"receipt_url": "/api/v1/proof/d4e5f6a7-b8c9-..."
}
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
curl -H "Authorization: Bearer swp_abc123..." \
https://ideaphase.app/api/v1/proof/d4e5f6a7-b8c9-1234-5678-9abcdef01234
Example Response (200 OK)
{
"receipt_type": "IdeaPhase API Encoding Proof",
"version": "1.0",
"generated_at": "2026-02-16T14:35:00+00:00",
"document": {
"document_id": "d4e5f6a7-b8c9-1234-5678-9abcdef01234",
"proof_hash": "a1b2c3d4e5f6...",
"input_hash": "e7f8a9b0c1d2...",
"output_hash": "3c4d5e6f7a8b...",
"processing_timestamp": "2026-02-16T14:32:01+00:00",
"processing_type": "api_encode",
"tier": "pro"
},
"chain": {
"previous_proof_hash": "f9e8d7c6b5a4...",
"chain_position": 7,
"api_key_prefix": "swp_a1b2"
},
"framework": "healthcare",
"verification": {
"algorithm": "SHA-256",
"encoding": "UTF-8",
"normalization": "CRLF -> LF",
"verify_url": "https://ideaphase.app/api/v1/proof/verify/a1b2c3d4e5f6...",
"chain_verify_url": "https://ideaphase.app/api/v1/proof/chain/swp_a1b2/verify"
},
"legal_notice": "This receipt provides cryptographic proof that the specified document was encoded through the IdeaPhase Symbol Word Protocol API at the indicated timestamp..."
}
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
curl https://ideaphase.app/api/v1/proof/verify/a1b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef
Example Response (200 OK)
{
"verified": true,
"message": "Proof verified successfully",
"document_id": "d4e5f6a7-b8c9-1234-5678-9abcdef01234",
"created_at": "2026-02-16T14:32:01+00:00",
"processing_type": "api_encode",
"chain": {
"has_chain": true,
"chain_position": 7,
"previous_proof_hash": "f9e8d7c6b5a4..."
}
}
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
curl https://ideaphase.app/api/v1/proof/chain/swp_a1b2/verify
Example Response (200 OK)
{
"valid": true,
"chain_length": 7,
"first_proof": "b0a1c2d3e4f5...",
"last_proof": "a1b2c3d4e5f6...",
"first_timestamp": "2026-01-15T09:12:00+00:00",
"last_timestamp": "2026-02-16T14:32:01+00:00",
"errors": []
}
Use Case: Share the verify URL with clients, auditors, or legal teams as independent proof that a document was encoded at a specific time. The public verification endpoint requires no login — anyone with the proof hash can verify it.
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
proof.created
Fired when a document is encoded and a new proof is generated
chain.verified
Fired when a proof chain integrity check completes
proof.shared
Fired when a proof is shared via a share token
proof.cross_referenced
Fired when proofs from different agents are cross-referenced
POST /api/v1/webhooks AUTH
Register a new webhook endpoint.
Request Body
{
"url": "https://your-app.com/webhooks/swp",
"events": ["proof.created", "chain.verified"]
}
Response (201 Created)
{
"id": 1,
"url": "https://your-app.com/webhooks/swp",
"events": ["proof.created", "chain.verified"],
"secret": "whsec_a1b2c3d4e5f6...",
"is_active": true,
"note": "Store the secret securely. Use it to verify webhook signatures."
}
GET /api/v1/webhooks AUTH
List all registered webhooks for your account.
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-SWP-Signature header. Verify it using your webhook secret:
{
"event": "proof.created",
"timestamp": "2026-03-01T14:32:01Z",
"data": {
"proof_hash": "a1b2c3d4e5f6...",
"document_id": "d4e5f6a7-b8c9-...",
"chain_position": 7,
"framework": "healthcare"
}
}
Verifying Webhook Signatures (Python)
import hmac, hashlib
def verify_webhook(payload_body, signature_header, webhook_secret):
expected = hmac.new(
webhook_secret.encode("utf-8"),
payload_body,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature_header)
Retry Policy: Failed webhook deliveries are retried up to 3 times with exponential backoff (1s, 4s, 16s delays). After 3 failures the delivery is abandoned. Ensure your endpoint returns a 2xx status code to acknowledge receipt.
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
- Agent A encodes a document and gets a proof hash
- Agent A calls
/api/v1/proof/share to generate a shareable token
- Agent A sends the share token to Agent B (via API, message queue, etc.)
- Agent B calls
/api/v1/proof/shared/{token} to verify the proof (public, no auth needed)
- 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)
{
"share_token": "eyJkYXRhIjoi...",
"expires_at": "2026-03-08T14:32:01+00:00",
"proof_hash": "a1b2c3d4e5f6...",
"verification_url": "https://ideaphase.app/api/v1/proof/shared/eyJkYXRhIjoi..."
}
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)
{
"valid": true,
"proof_hash": "a1b2c3d4e5f6...",
"document_id": "d4e5f6a7-b8c9-...",
"chain_position": 7,
"input_hash": "e7f8a9b0c1d2...",
"output_hash": "3c4d5e6f7a8b...",
"framework": "healthcare",
"timestamp": "2026-02-16T14:32:01+00:00",
"shared_by": "swp_a1b2"
}
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
{
"source_proof_hash": "your_proof_hash_here...",
"target_share_token": "eyJkYXRhIjoi..."
}
Response (200 OK)
{
"cross_reference_id": 1,
"source_proof_hash": "your_proof_hash...",
"target_proof_hash": "their_proof_hash...",
"target_key_prefix": "swp_x9y8",
"created_at": "2026-03-01T15:00:00+00:00"
}
GET /api/v1/proof/cross-references/{proof_hash} AUTH
List all cross-references linked to a specific proof (both directions).
Multi-Agent Use Case: In a pipeline where multiple AI agents process different stages of a document (e.g., Agent A does intake, Agent B does analysis, Agent C does compliance review), each agent creates its own proof. Cross-references link these proofs into a verifiable end-to-end audit trail across all agents.
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.
Version Strategy: V1 endpoints are locked and will continue to work indefinitely. V2 adds enhancements without breaking V1 consumers. You can also use V2 response format on V1 endpoints by sending the Accept-Version: v2 header.
V2 Response Enhancements
api_version
Response includes "api_version": "v2" field
request_id
Unique request identifier for tracing and support
X-RateLimit-Remaining
Response header showing remaining requests in current window
X-RateLimit-Reset
Response header with UTC timestamp when the limit resets
Structured Errors
Error responses include code and message fields inside an error object
POST /api/v2/encode AUTH
Same input as V1. Enhanced response with version metadata and rate limit info.
Request
curl -X POST https://ideaphase.app/api/v2/encode \
-H "Authorization: Bearer swp_abc123..." \
-H "Content-Type: application/json" \
-d '{"text": "Your document text here.", "framework": "general"}'
Response Headers
X-API-Version: 2.0
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 2026-03-01T15:00:00Z
Response Body (200 OK)
{
"api_version": "v2",
"request_id": "req_a1b2c3d4e5f6",
"swp_version": "1.0",
"encoding_id": "f7e8d9c0b1a2",
"tagged_document": { ... },
"prompt_template": "...",
"lora_guidance": { ... },
"metadata": { ... },
"proof": { ... }
}
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
{
"api_version": "v2",
"error": {
"code": "RATE_LIMITED",
"message": "Daily API limit exceeded (100/day)"
}
}
Version Negotiation on V1 Endpoints
If you want V2 response format but want to keep using V1 URLs, add the Accept-Version: v2 header:
curl -X POST https://ideaphase.app/api/v1/encode \
-H "Authorization: Bearer swp_abc123..." \
-H "Accept-Version: v2" \
-H "Content-Type: application/json" \
-d '{"text": "Your text here.", "framework": "general"}'
Migration Path: Start with V1 for stability. When you need rate limit headers or request IDs for debugging, switch to V2 endpoints or add the Accept-Version: v2 header. Both versions use the same API keys and authentication.
Rate Limits & Quotas
API access is rate-limited to ensure fair usage across all clients.
Rate Limit Response (429)
{
"error": "Daily API limit exceeded",
"limit": 100
}
V2 Rate Limit Headers
V2 endpoints (and V1 endpoints with Accept-Version: v2) include rate limit information in the response headers:
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 2026-03-01T15:00:00Z
Use these headers to implement client-side throttling and avoid hitting 429 errors.
Need higher limits? Contact
ideaphase.needs@gmail.com to discuss enterprise plans with custom rate limits and SLA guarantees.
Error Reference
All errors return JSON with an error field. Common HTTP status codes:
Example Error Responses
{ "error": "Missing 'text' field in request body" }
{ "error": "Missing or invalid Authorization header. Use: Bearer <your_api_key>" }
{
"error": "Active Pro subscription required to create API keys",
"upgrade_url": "/api/create-checkout"
}
{ "verified": false, "message": "No proof found with this hash" }
Security & Compliance
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.
Patent Protected: The Symbol Word Protocol classification algorithm runs entirely server-side. API consumers receive encoded output only — the tagging logic is never exposed. SWP is patent pending with the USPTO.
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
curl https://ideaphase.app/api/health
Example Response (200 OK)
{
"status": "healthy",
"components": {
"api_server": { "status": "up", "response_time_ms": 1 },
"database": { "status": "up", "response_time_ms": 12 },
"proof_chain": { "status": "up", "response_time_ms": 8 },
"encoding_engine": { "status": "up", "response_time_ms": 3 }
},
"timestamp": "2025-01-15T12:00:00.000Z",
"version": "1.0"
}
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
curl https://ideaphase.app/api/v1/discovery
Example Response (200 OK)
{
"version": "1.0",
"documentation": "https://ideaphase.app/swp-docs",
"endpoints": {
"encoding": {
"v1": [
{ "method": "POST", "path": "/api/v1/encode", "auth": "Bearer token", "description": "Encode text with SWP tags" },
{ "method": "POST", "path": "/api/v1/encode/batch", "auth": "Bearer token", "description": "Batch encode up to 20 texts" }
],
"v2": [ ]
},
"proofs": [ ],
"webhooks": [ ],
"api_keys": [ ],
"health": [
{ "method": "GET", "path": "/api/health", "auth": "none", "description": "System health check with component status" },
{ "method": "GET", "path": "/api/status", "auth": "none", "description": "System status overview" }
]
},
"rate_limits": {
"encoding": "10 per minute (per API key)",
"proofs": "30 per minute",
"health": "30 per minute",
"discovery": "10 per minute"
}
}
Integration Tip: Use the discovery endpoint to automatically configure your API client. The response includes all available endpoints, their authentication requirements, and current rate limits. This is the recommended starting point for new integrations.
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
curl -L https://ideaphase.app/docs
curl https://ideaphase.app/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
import requests
API_KEY = "swp_your_api_key_here"
BASE_URL = "https://ideaphase.app"
response = requests.post(
f"{BASE_URL}/api/v1/encode",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json={
"text": "Your document content here...",
"framework": "general"
}
)
result = response.json()
tagged_text = result["tagged_document"]["full_text"]
proof_id = result["proof"]["document_id"]
proof_hash = result["proof"]["proof_hash"]
print(f"Tagged document: {tagged_text[:200]}...")
print(f"Document ID: {proof_id}")
print(f"Proof hash: {proof_hash}")
print(f"Chain position: {result['proof']['chain_position']}")
verify = requests.get(f"{BASE_URL}/api/v1/proof/verify/{proof_hash}")
print(f"Verified: {verify.json()['verified']}")
JavaScript (Node.js)
const API_KEY = "swp_your_api_key_here";
const BASE_URL = "https://ideaphase.app";
async function encodeDocument(text, framework = "general") {
const response = await fetch(`${BASE_URL}/api/v1/encode`, {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ text, framework })
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.error);
}
return response.json();
}
const result = await encodeDocument(
"Contract clause: Party A shall deliver within 30 business days...",
"legal"
);
console.log("Phase:", result.tagged_document.core_tags.phase);
console.log("Weight:", result.tagged_document.core_tags.weight);
console.log("Proof:", result.proof.document_id);
console.log("Chain #:", result.proof.chain_position);
cURL — Full Workflow
RESPONSE=$(curl -s -X POST https://ideaphase.app/api/v1/encode \
-H "Authorization: Bearer swp_abc123..." \
-H "Content-Type: application/json" \
-d '{"text": "Deploy autonomous navigation module v2.3 with LIDAR failover.", "framework": "robotics"}')
PROOF_HASH=$(echo $RESPONSE | jq -r '.proof.proof_hash')
DOC_ID=$(echo $RESPONSE | jq -r '.proof.document_id')
curl -H "Authorization: Bearer swp_abc123..." \
https://ideaphase.app/api/v1/proof/$DOC_ID
curl https://ideaphase.app/api/v1/proof/verify/$PROOF_HASH
curl https://ideaphase.app/api/v1/proof/chain/swp_a1b2/verify
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.
Key Concept: Your LLM never needs the API key. You call IdeaPhase, get back structured SWP-tagged output with a ready-to-use prompt template, then feed that template to your local model. The SWP tags guide the model to produce more structured, deterministic output.
Start Here: Call
GET /api/v1/discovery to get a complete catalog of all available endpoints, their authentication requirements, and rate limits. This is the recommended first step when building a new integration. Need help? Visit the
AI Support Chat for instant answers.
How the Flow Works
Your Text
→
IdeaPhase API
→
SWP-Tagged Prompt
→
Your Local LLM
Your API key authenticates YOU to IdeaPhase — your LLM never sees it
- Send your raw text to the IdeaPhase
/api/v1/encode endpoint with your API key
- Receive back: SWP-tagged document + prompt template + LoRA fine-tuning guidance + cryptographic proof
- Take the
prompt_template from the response and send it to your local LLM
- The LLM reads the SWP tags and produces structured, compliance-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
from ideaphase import IdeaPhase
client = IdeaPhase(api_key="swp_your_key_here")
result = client.encode(
"Design a patient intake system for emergency departments.",
framework="healthcare"
)
prompt = result["prompt_template"]
import requests
llm_response = requests.post("http://localhost:11434/api/generate", json={
"model": "llama3",
"prompt": prompt,
"stream": False
})
print(llm_response.json()["response"])
verification = client.verify_proof(result["proof"]["proof_hash"])
print(f"Proof valid: {verification['verified']}")
JavaScript/TypeScript: Full Encode → Verify Workflow
import { IdeaPhase } from "ideaphase";
const client = new IdeaPhase({ apiKey: "swp_your_key_here" });
const result = await client.encode(
"Design a patient intake system for emergency departments.",
{ framework: "healthcare" }
);
const prompt = result.prompt_template;
const llmResponse = await fetch("http://localhost:11434/api/generate", {
method: "POST",
body: JSON.stringify({ model: "llama3", prompt, stream: false })
});
const llmResult = await llmResponse.json();
console.log(llmResult.response);
const verification = await client.verifyProof(result.proof.proof_hash);
console.log(`Proof valid: ${verification.verified}`);
SDK vs Raw HTTP: The SDK examples above replace ~15 lines of raw HTTP setup (headers, error parsing, URL construction) with 2–3 lines. See the SDKs tab for full SDK documentation including batch encoding, webhooks, and proof sharing. The raw HTTP examples below are provided for users who prefer direct API access.
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
curl https://ideaphase.app/api/v1/key/test -H "Authorization: Bearer YOUR_SWP_API_KEY"
Windows CMD (one line)
curl https://ideaphase.app/api/v1/key/test -H "Authorization: Bearer YOUR_SWP_API_KEY"
Windows PowerShell
curl.exe https://ideaphase.app/api/v1/key/test -H "Authorization: Bearer YOUR_SWP_API_KEY"
Expected response: {"valid": true, "key_prefix": "swp_XXXXXXXX", "is_founder": true, "message": "API key is valid and active"}
If you get "valid": false, the response will tell you exactly what went wrong (wrong format, extra characters, key not found, etc.).
Step 1: Encode with cURL
Choose your platform below. The commands do the same thing — the only difference is how each terminal handles quotes.
Important: All commands must be pasted as a single line. Replace YOUR_SWP_API_KEY with your actual API key (starts with swp_). If your terminal wraps the text visually, that's fine — just make sure you don't insert any line breaks when pasting.
Linux / Mac / Git Bash
curl -X POST https://ideaphase.app/api/v1/encode -H "Authorization: Bearer YOUR_SWP_API_KEY" -H "Content-Type: application/json" -d '{"text": "Design a patient intake system for emergency departments.", "framework": "healthcare"}'
Windows CMD
Inner quotes in the JSON body are escaped with \".
curl -X POST https://ideaphase.app/api/v1/encode -H "Authorization: Bearer YOUR_SWP_API_KEY" -H "Content-Type: application/json" -d "{\"text\": \"Design a patient intake system for emergency departments.\", \"framework\": \"healthcare\"}"
Windows PowerShell
Use curl.exe with the --% stop-parsing token. This tells PowerShell to pass everything after it directly to curl without any interpretation:
curl.exe --% -X POST https://ideaphase.app/api/v1/encode -H "Authorization: Bearer YOUR_SWP_API_KEY" -H "Content-Type: application/json" -d "{\"text\": \"Design a patient intake system for emergency departments.\", \"framework\": \"healthcare\"}"
PowerShell notes:
- Use
curl.exe (not curl) because PowerShell aliases curl to Invoke-WebRequest.
- The
--% (stop-parsing token) is the key — it prevents PowerShell from mangling your JSON. Everything after --% is passed exactly as typed.
- With
--%, use the same \" escaping as CMD.
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:
curl http://localhost:11434/api/generate -d '{"model": "llama3", "prompt": "[PASTE THE prompt_template VALUE HERE]", "stream": false}'
Windows CMD:
curl http://localhost:11434/api/generate -d "{\"model\": \"llama3\", \"prompt\": \"[PASTE THE prompt_template VALUE HERE]\", \"stream\": false}"
Windows PowerShell:
curl.exe --% http://localhost:11434/api/generate -d "{\"model\": \"llama3\", \"prompt\": \"[PASTE THE prompt_template VALUE HERE]\", \"stream\": false}"
Python Integration
A complete Python script showing the full workflow:
import requests
IDEAPHASE_URL = "https://YOUR-IDEAPHASE-URL"
SWP_API_KEY = "swp_your_api_key_here"
# Step 1: Encode with SWP
swp_response = requests.post(
f"{IDEAPHASE_URL}/api/v1/encode",
headers={
"Authorization": f"Bearer {SWP_API_KEY}",
"Content-Type": "application/json"
},
json={
"text": "Your document or idea text goes here.",
"framework": "general",
"include_extended_tags": True
}
)
result = swp_response.json()
prompt = result["prompt_template"]
# Step 2a: Send to Ollama
ollama_response = requests.post(
"http://localhost:11434/api/generate",
json={
"model": "llama3",
"prompt": prompt,
"stream": False
}
)
print(ollama_response.json()["response"])
# Step 2b: OR send to LM Studio (OpenAI-compatible)
lm_response = requests.post(
"http://localhost:1234/v1/chat/completions",
json={
"model": "local-model",
"messages": [
{"role": "system", "content": "Process this SWP-encoded document precisely."},
{"role": "user", "content": prompt}
],
"temperature": 0.3
}
)
print(lm_response.json()["choices"][0]["message"]["content"])
Ollama Setup
Ollama runs open-source models locally on your machine. It has a simple REST API that works perfectly with SWP.
- Install Ollama from ollama.ai
- Pull a model:
ollama pull llama3
- Start the server:
ollama serve (runs on port 11434)
- Use the Python script above or the downloaded integration script
Recommended models for SWP: Llama 3 (8B or 70B), Mistral 7B, Phi-3, or Qwen 2.5. Larger models follow SWP tags more precisely, but even 7B models show significant improvement with tagged input.
LM Studio Setup
LM Studio provides a GUI for running local models with an OpenAI-compatible API server.
- Download from lmstudio.ai
- Search and download any GGUF model (Llama 3, Mistral, etc.)
- Go to the "Local Server" tab and click "Start Server" (runs on port 1234)
- LM Studio exposes an OpenAI-compatible API — use the
/v1/chat/completions endpoint
import requests
prompt = result["prompt_template"] # From SWP encode response
response = requests.post(
"http://localhost:1234/v1/chat/completions",
json={
"model": "local-model",
"messages": [
{
"role": "system",
"content": "You are processing an SWP-encoded document. Follow all tag instructions precisely."
},
{
"role": "user",
"content": prompt
}
],
"temperature": 0.3,
"max_tokens": 2000
}
)
print(response.json()["choices"][0]["message"]["content"])
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
import requests
def swp_encode_tool(text, framework="general"):
"""
Agent tool: Pre-process text through SWP before LLM reasoning.
Add this as a custom tool in your agent framework.
"""
response = requests.post(
"https://YOUR-IDEAPHASE-URL/api/v1/encode",
headers={
"Authorization": "Bearer YOUR_SWP_API_KEY",
"Content-Type": "application/json"
},
json={"text": text, "framework": framework}
)
data = response.json()
return {
"tagged_text": data["tagged_document"]["full_text"],
"prompt": data["prompt_template"],
"proof_id": data.get("proof", {}).get("document_id"),
"tags": data["tagged_document"]["core_tags"]
}
# In your agent's workflow:
# 1. Agent receives a task
# 2. Agent calls swp_encode_tool() to tag relevant documents
# 3. Agent uses the tagged prompt for its LLM reasoning
# 4. Result: More structured, auditable agent output
Agent specific: Add the swp_encode_tool function as a custom tool in your Agent configuration. The agent can then call it to pre-process any document before reasoning. If your Agent runs in Docker, make sure the container can reach the IdeaPhase URL (use the public URL, not localhost).
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:
import requests
def send_to_any_openai_endpoint(prompt, base_url, api_key="not-needed", model="default"):
"""Works with: LM Studio, Ollama (OpenAI mode), vLLM,
text-generation-webui, LocalAI, and others."""
response = requests.post(
f"{base_url}/v1/chat/completions",
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {api_key}"
},
json={
"model": model,
"messages": [
{"role": "system", "content": "Process this SWP-encoded document precisely."},
{"role": "user", "content": prompt}
],
"temperature": 0.3
}
)
return response.json()["choices"][0]["message"]["content"]
# Examples:
# Ollama (OpenAI mode): send_to_any_openai_endpoint(prompt, "http://localhost:11434")
# LM Studio: send_to_any_openai_endpoint(prompt, "http://localhost:1234")
# vLLM: send_to_any_openai_endpoint(prompt, "http://localhost:8000")
# LocalAI: send_to_any_openai_endpoint(prompt, "http://localhost:8080")
What You Get Back from the API
Every encode call returns these key fields:
Founder Key vs. Pro Key
Security reminder: Never paste your API key directly into an LLM prompt or share it in chat. The key authenticates your API calls only — your LLM receives the prompt template (which contains the SWP tags and your document), not the key.
Verifying Proofs
Every encoded document gets a cryptographic proof. You can verify proofs publicly without authentication:
# Verify a specific proof (no API key needed)
curl https://YOUR-IDEAPHASE-URL/api/v1/proof/verify/YOUR_PROOF_HASH
# Check chain integrity for an API key
curl https://YOUR-IDEAPHASE-URL/api/v1/proof/chain/YOUR_KEY_PREFIX/verify
This is how you prove a document existed at a specific time and hasn't been tampered with — critical for regulated industries.
