External Python Calling API - Integration Requirements

This document outlines the requirements for the external Python API that will handle voice call scheduling, execution, and management for the Auto-Caller application. The Next.js frontend will interact with this API.

1. Authentication & Authorization

Mechanism: The Python API must expose a secure way for the Next.js backend to authenticate its requests. An API Key passed in the Authorization: Bearer <API_KEY> or a custom header (X-API-Key: <API_KEY>) is recommended. This key should be kept secret in the Next.js backend's environment variables.
User Context: Since the Next.js app manages users, every request from the Next.js backend to the Python API must include the authenticated user's unique identifier (e.g., userId from the NextAuth session, likely the MongoDB ObjectId string). The Python API must use this userId to scope all operations (creating, retrieving, updating, deleting calls) to the correct user. This is crucial for data isolation and security.

2. Required API Endpoints

The Python API should expose the following RESTful endpoints. All request/response bodies should be in JSON format.

POST /calls/schedule

Purpose: Schedule a new voice call.
Authentication: API Key + User Context required.

Request Body:

{
  "userId": "string (required, from NextAuth session)",
  "title": "string (required)",
  "contactName": "string (required)",
  "contactPhone": "string (required, E.164 format recommended)",
  "scheduledTime": "string (required, ISO 8601 UTC)",
  "durationMinutes": "integer (optional, defaults to e.g., 15)",
  "purpose": "string (optional)",
  "aiScriptTemplate": "string (optional, basic script or prompt)",
  "recordingEnabled": "boolean (optional, defaults to true)",
  "transcriptionEnabled": "boolean (optional, defaults to true)",
  "callbackUrl": "string (optional, URL for the Python API to send status updates/results back to the Next.js app)"
  // Any other relevant parameters for the voice provider
}

Expected Success Response (201 Created):

{
  "callId": "string (unique ID generated by Python API)",
  "status": "scheduled",
  "scheduledTime": "string (ISO 8601 UTC)"
}

Expected Error Responses: 400 (Bad Request), 401 (Unauthorized API Key), 500 (Internal Server Error).

POST /calls/{call_id}/start

Purpose: Initiate a previously scheduled call.
Authentication: API Key + User Context required.
URL Parameter: call_id (The ID returned by /calls/schedule).

Request Body:

{
  "userId": "string (required, must match the user who scheduled the call)"
  // Potentially override parameters if needed at start time
}

Expected Success Response (200 OK):

{
  "callId": "string",
  "status": "initiating" | "connecting" | "in-progress", // Initial status from voice provider
  "startTime": "string (ISO 8601 UTC)",
  "sessionDetails": { // Information from the voice provider needed by frontend (if any)
    "providerSessionId": "string"
    // other relevant details
  }
}

Expected Error Responses: 400, 401, 404 (Call not found or wrong user), 409 (Conflict, e.g., call already started/completed), 500.

POST /calls/{call_id}/end

Purpose: Manually request to end an ongoing call.
Authentication: API Key + User Context required.
URL Parameter: call_id.
Request Body:
```
{
  "userId": "string (required)"
}
```

Expected Success Response (200 OK):

{
  "callId": "string",
  "status": "ending" | "completed" // Status reflecting the end request
}

Expected Error Responses: 400, 401, 404, 409 (e.g., call not in progress), 500.

GET /calls/{call_id}/status

Purpose: Get the current status and potentially live details of a specific call. Useful for polling from the frontend.
Authentication: API Key + User Context required.
URL Parameter: call_id.
Query Parameter: userId=string (required).

Expected Success Response (200 OK):

{
  "callId": "string",
  "status": "scheduled | initiating | ringing | in-progress | completed | failed | cancelled",
  "startTime": "string (ISO 8601 UTC, if applicable)",
  "endTime": "string (ISO 8601 UTC, if applicable)",
  "durationSeconds": "integer (if applicable)",
  "sessionDetails": { // Live details if 'in-progress'
    // e.g., participants, live transcription snippets
  },
  "errorInfo": "string (if status is 'failed')"
}

Expected Error Responses: 400, 401, 404, 500.

GET /calls/{call_id}

Purpose: Retrieve the full details and results of a specific call (usually after completion).
Authentication: API Key + User Context required.
URL Parameter: call_id.
Query Parameter: userId=string (required).

Expected Success Response (200 OK):

{
  "callId": "string",
  "userId": "string",
  "title": "string",
  "contactName": "string",
  "contactPhone": "string",
  "scheduledTime": "string (ISO 8601 UTC)",
  "startTime": "string (ISO 8601 UTC, if applicable)",
  "endTime": "string (ISO 8601 UTC, if applicable)",
  "durationSeconds": "integer (if applicable)",
  "status": "completed | failed | cancelled", // Final statuses
  "purpose": "string",
  "recordingUrl": "string (URL to the recording, if available)",
  "transcriptionText": "string (Full transcription, if available)",
  "aiSummary": "string (AI-generated summary, if available)",
  "errorInfo": "string (if status is 'failed')",
  "cost": "float (optional, call cost)"
  // Any other relevant final details
}

Expected Error Responses: 400, 401, 404, 500.

GET /calls

Purpose: Retrieve a list of calls for the specified user.
Authentication: API Key + User Context required.
Query Parameters:
- userId=string (required)
- status=string (optional, filter by status)
- limit=integer (optional, pagination)
- offset=integer (optional, pagination)
- sortBy=string (optional, e.g., 'scheduledTime')
- order=string (optional, 'asc' or 'desc')

Expected Success Response (200 OK):

{
  "calls": [
    {
      "callId": "string",
      "title": "string",
      "contactName": "string",
      "scheduledTime": "string (ISO 8601 UTC)",
      "status": "string",
      "durationSeconds": "integer (if applicable)"
      // Include a subset of fields suitable for a list view
    }
    // ... more calls
  ],
  "totalCount": "integer",
  "limit": "integer",
  "offset": "integer"
}

Expected Error Responses: 400, 401, 500.

DELETE /calls/{call_id}

Purpose: Cancel/delete a call, typically only allowed if it's still in 'scheduled' state.
Authentication: API Key + User Context required.
URL Parameter: call_id.
Request Body:
```
{
  "userId": "string (required)"
}
```
Expected Success Response (200 OK or 204 No Content):
```
{
  "message": "Call cancelled successfully"
}
```
Expected Error Responses: 400, 401, 404, 409 (e.g., call not in deletable state), 500.

POST /webhooks/call_updates (Optional but Recommended)

Purpose: An endpoint on the Next.js backend that the Python API can call to push asynchronous updates (e.g., call ended, transcription ready, recording ready, call failed). This avoids constant polling from the Next.js app.
Authentication: The Python API should include a secret token in the webhook request (e.g., in a header) that the Next.js backend can verify.

Request Body (Example):

{
  "eventType": "call.completed | call.failed | transcription.ready | recording.ready",
  "callId": "string",
  "timestamp": "string (ISO 8601 UTC)",
  "data": {
    // Event-specific data, e.g., recordingUrl, transcriptionText, errorInfo
  }
}

Expected Response (from Next.js): 200 OK (Acknowledgement).

3. Data Considerations

The Python API will be the source of truth for call status and results (recording, transcription, summary).
The Next.js application will need to store the callId generated by the Python API to correlate calls. It might cache some call details retrieved from the Python API but should rely on the Python API for the latest status and results.
Error handling should be robust, providing clear error messages in the JSON response body when possible.

4. Security

Protect the API Key used by the Next.js backend.
Strictly enforce userId checks on every operation in the Python API.
Implement rate limiting on the Python API endpoints.
Validate all incoming data (URL parameters, query parameters, request bodies).
Use HTTPS for all communication.
If using webhooks, verify the source using a shared secret.

This specification should provide a solid foundation for building the external Python calling API and ensuring it integrates correctly with your Next.js frontend.# External Python Calling API - Integration Requirements

This document outlines the requirements for the external Python API that will handle voice call scheduling, execution, and management for the Auto-Caller application. The Next.js frontend will interact with this API.

1. Authentication & Authorization

Mechanism: The Python API must expose a secure way for the Next.js backend to authenticate its requests. An API Key passed in the Authorization: Bearer <API_KEY> or a custom header (X-API-Key: <API_KEY>) is recommended. This key should be kept secret in the Next.js backend's environment variables.
User Context: Since the Next.js app manages users, every request from the Next.js backend to the Python API must include the authenticated user's unique identifier (e.g., userId from the NextAuth session, likely the MongoDB ObjectId string). The Python API must use this userId to scope all operations (creating, retrieving, updating, deleting calls) to the correct user. This is crucial for data isolation and security.

2. Required API Endpoints

The Python API should expose the following RESTful endpoints. All request/response bodies should be in JSON format.

POST /calls/schedule

Purpose: Schedule a new voice call.
Authentication: API Key + User Context required.

Request Body:

{
  "userId": "string (required, from NextAuth session)",
  "title": "string (required)",
  "contactName": "string (required)",
  "contactPhone": "string (required, E.164 format recommended)",
  "scheduledTime": "string (required, ISO 8601 UTC)",
  "durationMinutes": "integer (optional, defaults to e.g., 15)",
  "purpose": "string (optional)",
  "aiScriptTemplate": "string (optional, basic script or prompt)",
  "recordingEnabled": "boolean (optional, defaults to true)",
  "transcriptionEnabled": "boolean (optional, defaults to true)",
  "callbackUrl": "string (optional, URL for the Python API to send status updates/results back to the Next.js app)"
  // Any other relevant parameters for the voice provider
}

Expected Success Response (201 Created):

{
  "callId": "string (unique ID generated by Python API)",
  "status": "scheduled",
  "scheduledTime": "string (ISO 8601 UTC)"
}

Expected Error Responses: 400 (Bad Request), 401 (Unauthorized API Key), 500 (Internal Server Error).

POST /calls/{call_id}/start

Purpose: Initiate a previously scheduled call.
Authentication: API Key + User Context required.
URL Parameter: call_id (The ID returned by /calls/schedule).

Request Body:

{
  "userId": "string (required, must match the user who scheduled the call)"
  // Potentially override parameters if needed at start time
}

Expected Success Response (200 OK):

{
  "callId": "string",
  "status": "initiating" | "connecting" | "in-progress", // Initial status from voice provider
  "startTime": "string (ISO 8601 UTC)",
  "sessionDetails": { // Information from the voice provider needed by frontend (if any)
    "providerSessionId": "string"
    // other relevant details
  }
}

Expected Error Responses: 400, 401, 404 (Call not found or wrong user), 409 (Conflict, e.g., call already started/completed), 500.

POST /calls/{call_id}/end

Purpose: Manually request to end an ongoing call.
Authentication: API Key + User Context required.
URL Parameter: call_id.
Request Body:
```
{
  "userId": "string (required)"
}
```

Expected Success Response (200 OK):

{
  "callId": "string",
  "status": "ending" | "completed" // Status reflecting the end request
}

Expected Error Responses: 400, 401, 404, 409 (e.g., call not in progress), 500.

GET /calls/{call_id}/status

Purpose: Get the current status and potentially live details of a specific call. Useful for polling from the frontend.
Authentication: API Key + User Context required.
URL Parameter: call_id.
Query Parameter: userId=string (required).

Expected Success Response (200 OK):

{
  "callId": "string",
  "status": "scheduled | initiating | ringing | in-progress | completed | failed | cancelled",
  "startTime": "string (ISO 8601 UTC, if applicable)",
  "endTime": "string (ISO 8601 UTC, if applicable)",
  "durationSeconds": "integer (if applicable)",
  "sessionDetails": { // Live details if 'in-progress'
    // e.g., participants, live transcription snippets
  },
  "errorInfo": "string (if status is 'failed')"
}

Expected Error Responses: 400, 401, 404, 500.

GET /calls/{call_id}

Purpose: Retrieve the full details and results of a specific call (usually after completion).
Authentication: API Key + User Context required.
URL Parameter: call_id.
Query Parameter: userId=string (required).

Expected Success Response (200 OK):

{
  "callId": "string",
  "userId": "string",
  "title": "string",
  "contactName": "string",
  "contactPhone": "string",
  "scheduledTime": "string (ISO 8601 UTC)",
  "startTime": "string (ISO 8601 UTC, if applicable)",
  "endTime": "string (ISO 8601 UTC, if applicable)",
  "durationSeconds": "integer (if applicable)",
  "status": "completed | failed | cancelled", // Final statuses
  "purpose": "string",
  "recordingUrl": "string (URL to the recording, if available)",
  "transcriptionText": "string (Full transcription, if available)",
  "aiSummary": "string (AI-generated summary, if available)",
  "errorInfo": "string (if status is 'failed')",
  "cost": "float (optional, call cost)"
  // Any other relevant final details
}

Expected Error Responses: 400, 401, 404, 500.

GET /calls

Purpose: Retrieve a list of calls for the specified user.
Authentication: API Key + User Context required.
Query Parameters:
- userId=string (required)
- status=string (optional, filter by status)
- limit=integer (optional, pagination)
- offset=integer (optional, pagination)
- sortBy=string (optional, e.g., 'scheduledTime')
- order=string (optional, 'asc' or 'desc')

Expected Success Response (200 OK):

{
  "calls": [
    {
      "callId": "string",
      "title": "string",
      "contactName": "string",
      "scheduledTime": "string (ISO 8601 UTC)",
      "status": "string",
      "durationSeconds": "integer (if applicable)"
      // Include a subset of fields suitable for a list view
    }
    // ... more calls
  ],
  "totalCount": "integer",
  "limit": "integer",
  "offset": "integer"
}

Expected Error Responses: 400, 401, 500.

DELETE /calls/{call_id}

Purpose: Cancel/delete a call, typically only allowed if it's still in 'scheduled' state.
Authentication: API Key + User Context required.
URL Parameter: call_id.
Request Body:
```
{
  "userId": "string (required)"
}
```
Expected Success Response (200 OK or 204 No Content):
```
{
  "message": "Call cancelled successfully"
}
```
Expected Error Responses: 400, 401, 404, 409 (e.g., call not in deletable state), 500.

POST /webhooks/call_updates (Optional but Recommended)

Purpose: An endpoint on the Next.js backend that the Python API can call to push asynchronous updates (e.g., call ended, transcription ready, recording ready, call failed). This avoids constant polling from the Next.js app.
Authentication: The Python API should include a secret token in the webhook request (e.g., in a header) that the Next.js backend can verify.

Request Body (Example):

{
  "eventType": "call.completed | call.failed | transcription.ready | recording.ready",
  "callId": "string",
  "timestamp": "string (ISO 8601 UTC)",
  "data": {
    // Event-specific data, e.g., recordingUrl, transcriptionText, errorInfo
  }
}

Expected Response (from Next.js): 200 OK (Acknowledgement).

3. Data Considerations

The Python API will be the source of truth for call status and results (recording, transcription, summary).
The Next.js application will need to store the callId generated by the Python API to correlate calls. It might cache some call details retrieved from the Python API but should rely on the Python API for the latest status and results.
Error handling should be robust, providing clear error messages in the JSON response body when possible.

4. Security

Protect the API Key used by the Next.js backend.
Strictly enforce userId checks on every operation in the Python API.
Implement rate limiting on the Python API endpoints.
Validate all incoming data (URL parameters, query parameters, request bodies).
Use HTTPS for all communication.
If using webhooks, verify the source using a shared secret.

This specification should provide a solid foundation for building the external Python calling API and ensuring it integrates correctly with your Next.js frontend.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

api.md

api.md

External Python Calling API - Integration Requirements

1. Authentication & Authorization

2. Required API Endpoints

POST /calls/schedule

POST /calls/{call_id}/start

POST /calls/{call_id}/end

GET /calls/{call_id}/status

GET /calls/{call_id}

GET /calls

DELETE /calls/{call_id}

POST /webhooks/call_updates (Optional but Recommended)

3. Data Considerations

4. Security

1. Authentication & Authorization

2. Required API Endpoints

POST /calls/schedule

POST /calls/{call_id}/start

POST /calls/{call_id}/end

GET /calls/{call_id}/status

GET /calls/{call_id}

GET /calls

DELETE /calls/{call_id}

POST /webhooks/call_updates (Optional but Recommended)

3. Data Considerations

4. Security

Files

api.md

Latest commit

History

api.md

File metadata and controls

External Python Calling API - Integration Requirements

1. Authentication & Authorization

2. Required API Endpoints

POST /calls/schedule

POST /calls/{call_id}/start

POST /calls/{call_id}/end

GET /calls/{call_id}/status

GET /calls/{call_id}

GET /calls

DELETE /calls/{call_id}

POST /webhooks/call_updates (Optional but Recommended)

3. Data Considerations

4. Security

1. Authentication & Authorization

2. Required API Endpoints

POST /calls/schedule

POST /calls/{call_id}/start

POST /calls/{call_id}/end

GET /calls/{call_id}/status

GET /calls/{call_id}

GET /calls

DELETE /calls/{call_id}

POST /webhooks/call_updates (Optional but Recommended)

3. Data Considerations

4. Security