Skip to content

API.md

Latest commit

 

History

History
731 lines (629 loc) · 12.4 KB

API.md

File metadata and controls

731 lines (629 loc) · 12.4 KB
Raw

MYND Prompt Phylogeny - API Documentation

Base URL

Production: https://api.myndphylogeny.com/v1
Development: http://localhost:8080/v1

Authentication

All API requests require authentication using one of:

  • JWT Token: Authorization: Bearer <token>
  • API Key: X-API-Key: <api_key>

API Endpoints (25+)

🔐 Authentication Endpoints

1. Register

POST /auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "first_name": "John",
  "last_name": "Doe",
  "organization_name": "My Company"
}

Response: 201 Created
{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "owner"
  },
  "organization": {
    "id": "uuid",
    "name": "My Company",
    "slug": "my-company"
  },
  "tokens": {
    "access_token": "jwt_token",
    "refresh_token": "jwt_token",
    "expires_at": "2024-01-01T00:00:00Z"
  }
}

2. Login

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123!"
}

Response: 200 OK
{
  "user": { "id": "uuid", "email": "user@example.com" },
  "tokens": {
    "access_token": "jwt_token",
    "refresh_token": "jwt_token"
  }
}

3. Refresh Token

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "jwt_token"
}

Response: 200 OK
{
  "access_token": "new_jwt_token",
  "refresh_token": "new_jwt_token"
}

4. OAuth - Google

GET /auth/oauth/google
Response: Redirect to Google OAuth

5. OAuth - GitHub

GET /auth/oauth/github
Response: Redirect to GitHub OAuth

6. Logout

POST /auth/logout
Authorization: Bearer <token>

Response: 204 No Content

👥 User & Organization Endpoints

7. Get Current User

GET /users/me
Authorization: Bearer <token>

Response: 200 OK
{
  "id": "uuid",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "avatar_url": "https://...",
  "role": "owner",
  "organization": {
    "id": "uuid",
    "name": "My Company",
    "subscription_plan": "pro"
  }
}

8. Update User

PATCH /users/me
Authorization: Bearer <token>
Content-Type: application/json

{
  "first_name": "Johnny",
  "last_name": "Doe"
}

Response: 200 OK
{
  "id": "uuid",
  "first_name": "Johnny",
  "last_name": "Doe"
}

9. List Organization Members

GET /organizations/members
Authorization: Bearer <token>

Response: 200 OK
{
  "members": [
    {
      "id": "uuid",
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "role": "owner",
      "joined_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1
}

10. Invite Member

POST /organizations/members/invite
Authorization: Bearer <token>
Content-Type: application/json

{
  "email": "new@example.com",
  "role": "member"
}

Response: 201 Created
{
  "invitation_id": "uuid",
  "email": "new@example.com",
  "role": "member"
}

📁 Projects Endpoints

11. List Projects

GET /projects
Authorization: Bearer <token>
Query Parameters:
  - page: number (default: 1)
  - limit: number (default: 20)
  - search: string

Response: 200 OK
{
  "projects": [
    {
      "id": "uuid",
      "name": "Customer Support Prompts",
      "description": "Evolution of support prompts",
      "prompt_count": 42,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

12. Create Project

POST /projects
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Customer Support Prompts",
  "description": "Track evolution of support prompts",
  "is_public": false
}

Response: 201 Created
{
  "id": "uuid",
  "name": "Customer Support Prompts",
  "description": "Track evolution of support prompts",
  "created_at": "2024-01-01T00:00:00Z"
}

13. Get Project

GET /projects/{projectId}
Authorization: Bearer <token>

Response: 200 OK
{
  "id": "uuid",
  "name": "Customer Support Prompts",
  "description": "Track evolution of support prompts",
  "prompt_count": 42,
  "tree_count": 2,
  "created_at": "2024-01-01T00:00:00Z",
  "created_by": {
    "id": "uuid",
    "name": "John Doe"
  }
}

14. Update Project

PATCH /projects/{projectId}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Project Name",
  "description": "Updated description"
}

Response: 200 OK
{
  "id": "uuid",
  "name": "Updated Project Name",
  "description": "Updated description"
}

15. Delete Project

DELETE /projects/{projectId}
Authorization: Bearer <token>

Response: 204 No Content

💡 Prompts Endpoints

16. List Prompts

GET /projects/{projectId}/prompts
Authorization: Bearer <token>
Query Parameters:
  - page: number
  - limit: number
  - search: string
  - sort: fitness_score|-fitness_score|created_at
  - is_archived: boolean

Response: 200 OK
{
  "prompts": [
    {
      "id": "uuid",
      "title": "Support Response v3",
      "version": 3,
      "dna_fingerprint": "a1b2c3...",
      "avg_fitness": 0.8742,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 42
}

17. Create Prompt

POST /projects/{projectId}/prompts
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Support Response v4",
  "content": "You are a helpful customer support agent...",
  "description": "Improved empathy version",
  "parent_id": "uuid_of_v3",
  "temperature": 0.7,
  "max_tokens": 1024,
  "model": "gpt-4"
}

Response: 201 Created
{
  "id": "uuid",
  "title": "Support Response v4",
  "version": 4,
  "dna_fingerprint": "d4e5f6...",
  "embedding_generated": true,
  "parent_id": "uuid_of_v3",
  "created_at": "2024-01-01T00:00:00Z"
}

18. Get Prompt Details

GET /prompts/{promptId}
Authorization: Bearer <token>

Response: 200 OK
{
  "id": "uuid",
  "project_id": "uuid",
  "title": "Support Response v4",
  "content": "You are a helpful customer support agent...",
  "version": 4,
  "dna_fingerprint": "d4e5f6...",
  "parent_id": "uuid_of_v3",
  "avg_fitness": 0.9123,
  "fitness_breakdown": {
    "accuracy": 0.94,
    "relevance": 0.89,
    "coherence": 0.92,
    "creativity": 0.78
  },
  "mutation_count": 3,
  "created_at": "2024-01-01T00:00:00Z"
}

19. Get Prompt Lineage

GET /prompts/{promptId}/lineage
Authorization: Bearer <token>

Response: 200 OK
{
  "ancestors": [
    { "id": "uuid_v1", "version": 1, "fitness": 0.72 },
    { "id": "uuid_v2", "version": 2, "fitness": 0.78 },
    { "id": "uuid_v3", "version": 3, "fitness": 0.87 }
  ],
  "current": { "id": "uuid_v4", "version": 4, "fitness": 0.91 },
  "descendants": []
}

20. Get Prompt Mutations

GET /prompts/{promptId}/mutations
Authorization: Bearer <token>

Response: 200 OK
{
  "mutations": [
    {
      "id": "uuid",
      "mutation_type": "substitution",
      "semantic_distance": 0.1234,
      "edit_distance": 15,
      "original_text": "...",
      "mutated_text": "...",
      "detected_at": "2024-01-01T00:00:00Z"
    }
  ]
}

🌳 Phylogeny Tree Endpoints

21. List Trees

GET /projects/{projectId}/trees
Authorization: Bearer <token>

Response: 200 OK
{
  "trees": [
    {
      "id": "uuid",
      "name": "Main Evolution Tree",
      "algorithm": "upgma",
      "node_count": 42,
      "last_recalculated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

22. Create Tree

POST /projects/{projectId}/trees
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Main Evolution Tree",
  "algorithm": "upgma",
  "prompt_ids": ["uuid1", "uuid2", "uuid3"]
}

Response: 201 Created
{
  "id": "uuid",
  "name": "Main Evolution Tree",
  "status": "building",
  "estimated_time_seconds": 30
}

23. Get Tree Data

GET /trees/{treeId}
Authorization: Bearer <token>

Response: 200 OK
{
  "id": "uuid",
  "name": "Main Evolution Tree",
  "algorithm": "upgma",
  "root_node": {
    "id": "uuid",
    "prompt_id": "uuid",
    "children": [
      {
        "id": "uuid",
        "prompt_id": "uuid",
        "branch_length": 0.1234,
        "fitness_score": 0.87,
        "children": []
      }
    ]
  },
  "node_count": 42,
  "last_recalculated_at": "2024-01-01T00:00:00Z"
}

24. Recalculate Tree

POST /trees/{treeId}/recalculate
Authorization: Bearer <token>

Response: 202 Accepted
{
  "status": "recalculating",
  "job_id": "uuid"
}

🧬 Hybridization Endpoints

25. Create Hybrid

POST /projects/{projectId}/hybrids
Authorization: Bearer <token>
Content-Type: application/json

{
  "parent_a_id": "uuid_prompt1",
  "parent_b_id": "uuid_prompt2",
  "method": "semantic_blend",
  "weights": [0.6, 0.4]
}

Response: 201 Created
{
  "id": "uuid",
  "offspring_prompt": {
    "id": "uuid",
    "title": "Hybrid: Prompt1 + Prompt2",
    "content": "Hybridized content...",
    "dna_fingerprint": "hybrid_hash..."
  },
  "predicted_fitness_improvement": 0.0842
}

26. List Hybrids

GET /projects/{projectId}/hybrids
Authorization: Bearer <token>

Response: 200 OK
{
  "hybrids": [
    {
      "id": "uuid",
      "parent_a": { "id": "uuid", "title": "Prompt A" },
      "parent_b": { "id": "uuid", "title": "Prompt B" },
      "offspring": { "id": "uuid", "title": "Hybrid Offspring" },
      "fitness_improvement": 0.0842,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

📊 Fitness & Analytics Endpoints

27. Record Fitness Score

POST /prompts/{promptId}/fitness
Authorization: Bearer <token>
Content-Type: application/json

{
  "metric_name": "accuracy",
  "score": 0.9456,
  "test_case_id": "uuid",
  "model_used": "gpt-4",
  "latency_ms": 1247,
  "token_count": 842
}

Response: 201 Created
{
  "id": "uuid",
  "new_avg_fitness": 0.8923
}

28. Get Fitness History

GET /prompts/{promptId}/fitness/history
Authorization: Bearer <token>
Query Parameters:
  - start_date: ISO date
  - end_date: ISO date
  - interval: hour|day|week

Response: 200 OK
{
  "history": [
    {
      "time": "2024-01-01T00:00:00Z",
      "avg_fitness": 0.85,
      "sample_count": 5
    }
  ]
}

29. Detect Convergent Evolution

POST /projects/{projectId}/analytics/convergent-evolution
Authorization: Bearer <token>

Response: 200 OK
{
  "clusters": [
    {
      "cluster_id": "uuid",
      "prompts": [
        { "id": "uuid1", "similarity": 0.98 },
        { "id": "uuid2", "similarity": 0.97 }
      ],
      "centroid_embedding": [...],
      "avg_fitness": 0.89
    }
  ]
}

🧪 Test Cases Endpoints

30. Run Test Suite

POST /projects/{projectId}/test-runs
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Regression Test v2.0",
  "prompt_ids": ["uuid1", "uuid2"],
  "test_case_ids": ["uuid1", "uuid2", "uuid3"]
}

Response: 201 Created
{
  "id": "uuid",
  "status": "running",
  "progress": 0
}

31. Get Test Run Results

GET /test-runs/{testRunId}
Authorization: Bearer <token>

Response: 200 OK
{
  "id": "uuid",
  "name": "Regression Test v2.0",
  "status": "completed",
  "results": [
    {
      "prompt_id": "uuid",
      "test_case_id": "uuid",
      "scores": {
        "accuracy": 0.92,
        "relevance": 0.88
      },
      "output": "LLM output text..."
    }
  ],
  "completed_at": "2024-01-01T00:00:00Z"
}

💳 Billing Endpoints

32. Create Checkout Session

POST /billing/checkout
Authorization: Bearer <token>
Content-Type: application/json

{
  "plan": "professional",
  "billing_cycle": "monthly"
}

Response: 200 OK
{
  "checkout_url": "https://checkout.stripe.com/..."
}

33. Get Subscription

GET /billing/subscription
Authorization: Bearer <token>

Response: 200 OK
{
  "plan": "professional",
  "status": "active",
  "current_period_end": "2024-02-01T00:00:00Z",
  "usage": {
    "prompts_used": 42,
    "prompts_limit": 1000
  }
}

Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Error Codes

  • VALIDATION_ERROR: Input validation failed
  • AUTHENTICATION_ERROR: Invalid or missing token
  • AUTHORIZATION_ERROR: Insufficient permissions
  • NOT_FOUND: Resource not found
  • CONFLICT: Resource conflict
  • RATE_LIMITED: Too many requests
  • INTERNAL_ERROR: Server error