Developer API Integration Guide

Integrate Promptha's AI capabilities directly into your applications.

API Overview

Promptha provides RESTful APIs for:

• Running fabrics programmatically
• Creating chat sessions with Asks
• Managing knowledge bases
• Batch processing

Authentication

API Keys

Generate API keys in Dashboard > Settings > API:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.promptha.com/v1/fabrics

Key Types

• Development: Rate-limited, for testing
• Production: Full rate limits, for live apps

Running Fabrics

Execute a Fabric

const response = await fetch('https://api.promptha.com/v1/fabrics/run', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fabricId: 'fabric_abc123',
    inputs: {
      topic: 'AI in healthcare',
      tone: 'professional',
      length: 'medium'
    }
  })
});

const result = await response.json();
console.log(result.output);

Async Execution

For long-running fabrics:

// Start execution
const { executionId } = await startFabric(fabricId, inputs);

// Poll for completion
const result = await pollExecution(executionId);

Chat API (Asks)

Create a Session

const session = await fetch('https://api.promptha.com/v1/asks/sessions', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  body: JSON.stringify({
    askId: 'ask_xyz789',
    context: { userId: 'user123' }
  })
});

Send Messages

const response = await fetch(`https://api.promptha.com/v1/asks/sessions/${sessionId}/messages`, {
  method: 'POST',
  body: JSON.stringify({
    content: 'Generate a product description for...',
    attachments: [] // optional image URLs
  })
});

Streaming Responses

const stream = await fetch(url, {
  headers: { 'Accept': 'text/event-stream' }
});

for await (const chunk of stream) {
  process.stdout.write(chunk.content);
}

Webhooks

Configure Webhooks

Receive notifications when:

• Fabric execution completes
• Batch processing finishes
• Credits run low

{
  "url": "https://yourapp.com/webhooks/promptha",
  "events": ["fabric.completed", "batch.completed"],
  "secret": "webhook_secret_for_verification"
}

Verify Signatures

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === expected;
}

Rate Limits

Plan	Requests/min	Concurrent
Starter	60	5
Pro	300	20
Team	1000	50
Business	3000	100

Handle rate limits gracefully:

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await sleep(retryAfter * 1000);
  return retry(request);
}

SDKs

Official SDKs available:

• JavaScript/TypeScript: npm install @promptha/sdk
• Python: pip install promptha
• Go: go get github.com/promptha/go-sdk

SDK Example

import { Promptha } from '@promptha/sdk';

const client = new Promptha({ apiKey: process.env.PROMPTHA_API_KEY });

const result = await client.fabrics.run('fabric_id', {
  topic: 'AI trends',
  format: 'blog'
});

Best Practices

1. Cache responses when possible
2. Use webhooks for async operations
3. Handle errors gracefully
4. Monitor usage to avoid overages
5. Secure API keys in environment variables

Resources

• API Reference
• SDK Documentation
• Code Examples