Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
348 lines (297 loc) · 5.5 KB

API_DOCUMENTATION.md

File metadata and controls

348 lines (297 loc) · 5.5 KB
Raw

API Documentation

Base URL

http://localhost:3001/api

All endpoints except authentication require a JWT token in the Authorization header:

Authorization: Bearer <token>

Authentication

Register User

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

{
  "username": "string",
  "password": "string",
  "email": "string (optional)"
}

Response:

{
  "token": "jwt_token_string",
  "user": {
    "id": "uuid",
    "username": "string",
    "email": "string"
  }
}

Login

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

{
  "username": "string",
  "password": "string"
}

Response:

{
  "token": "jwt_token_string",
  "user": {
    "id": "uuid",
    "username": "string",
    "email": "string"
  }
}

Personas

Get All Personas

GET /personas
Authorization: Bearer <token>

Response:

[
  {
    "id": "uuid",
    "user_id": "uuid",
    "name": "string",
    "type": "synthetic_user" | "advisor",
    "description": "string",
    "avatar_url": "string",
    "metadata": {},
    "created_at": "timestamp",
    "updated_at": "timestamp"
  }
]

Get Persona by ID

GET /personas/:id
Authorization: Bearer <token>

Create Persona

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

{
  "name": "string",
  "type": "synthetic_user" | "advisor",
  "description": "string",
  "avatar_url": "string",
  "metadata": {}
}

Update Persona

PUT /personas/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "string (optional)",
  "description": "string (optional)",
  "avatar_url": "string (optional)",
  "metadata": {} (optional)
}

Delete Persona

DELETE /personas/:id
Authorization: Bearer <token>

Get Persona Files

GET /personas/:personaId/files
Authorization: Bearer <token>

Response:

[
  {
    "id": "uuid",
    "persona_id": "uuid",
    "name": "string",
    "content": "string",
    "type": "markdown" | "pdf_analysis" | "linked_in_profile",
    "created_at": "timestamp"
  }
]

Create Persona File

POST /personas/:personaId/files
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "string",
  "content": "string",
  "type": "markdown" | "pdf_analysis" | "linked_in_profile"
}

Chat Sessions

Get All Chat Sessions

GET /chat/sessions
Authorization: Bearer <token>

Response:

[
  {
    "id": "uuid",
    "user_id": "uuid",
    "name": "string",
    "created_at": "timestamp",
    "updated_at": "timestamp"
  }
]

Get Chat Session by ID

GET /chat/sessions/:id
Authorization: Bearer <token>

Create Chat Session

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

{
  "name": "string",
  "personaIds": ["uuid", "uuid"]
}

Update Chat Session

PUT /chat/sessions/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "string"
}

Delete Chat Session

DELETE /chat/sessions/:id
Authorization: Bearer <token>

Get Session Personas

GET /chat/sessions/:sessionId/personas
Authorization: Bearer <token>

Get Session Messages

GET /chat/sessions/:sessionId/messages
Authorization: Bearer <token>

Response:

[
  {
    "id": "uuid",
    "session_id": "uuid",
    "sender_type": "user" | "persona",
    "persona_id": "uuid (optional)",
    "content": "string",
    "created_at": "timestamp"
  }
]

Create Message

POST /chat/sessions/:sessionId/messages
Authorization: Bearer <token>
Content-Type: application/json

{
  "sender_type": "user" | "persona",
  "persona_id": "uuid (optional, required if sender_type is persona)",
  "content": "string"
}

Simulation Sessions

Get All Simulation Sessions

GET /simulations
Authorization: Bearer <token>

Response:

[
  {
    "id": "uuid",
    "user_id": "uuid",
    "persona_id": "uuid",
    "mode": "web_page" | "marketing" | "sales_pitch" | "investor_pitch",
    "bg_info": "string",
    "opening_line": "string (optional)",
    "stimulus_image": "string (optional)",
    "mime_type": "string (optional)",
    "name": "string",
    "created_at": "timestamp",
    "updated_at": "timestamp"
  }
]

Get Simulation Session by ID

GET /simulations/:id
Authorization: Bearer <token>

Create Simulation Session

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

{
  "persona_id": "uuid",
  "mode": "web_page" | "marketing" | "sales_pitch" | "investor_pitch",
  "bg_info": "string",
  "opening_line": "string (optional)",
  "stimulus_image": "string (optional)",
  "mime_type": "string (optional)",
  "name": "string"
}

Update Simulation Session

PUT /simulations/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "string (optional)",
  "bg_info": "string (optional)",
  "opening_line": "string (optional)",
  "stimulus_image": "string (optional)",
  "mime_type": "string (optional)"
}

Delete Simulation Session

DELETE /simulations/:id
Authorization: Bearer <token>

Error Responses

All errors follow this format:

{
  "error": "Error message description"
}

Status Codes:

  • 200 - Success
  • 201 - Created
  • 204 - No Content (successful delete)
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 409 - Conflict (e.g., username already exists)
  • 500 - Internal Server Error