> For the complete documentation index, see [llms.txt](https://feeda.gitbook.io/ferdy-framework/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://feeda.gitbook.io/ferdy-framework/5.-api-reference.md).
# 5. API Reference
This section provides a detailed guide to the Ferdy Framework's APIs, including authentication, endpoints, methods, parameters, and example responses. The API is designed to enable seamless integration with Ferdy’s features, such as conversational AI, task execution, and user management.
### **5.1 Authentication**
Ferdy APIs use OAuth 2.0 and API Keys for secure access.
**API Key Authentication**
1. **Obtain your API key from the Ferdy Developer Portal.**
Include the API key in the Authorization header for each request:\
`Authorization: Bearer YOUR_API_KEY`
2. **OAuth 2.0**
1. Generate an access token using the /auth/token endpoint.
2. Use the token for authenticated API requests.
**Example: Generate Token**\
Endpoint: POST /auth/token
\
**Request:** json
`{`
`"client_id": "your-client-id",`
`"client_secret": "your-client-secret",`
`"grant_type": "client_credentials"`
`}`
\
**Response:** json
`{`
`"access_token": "your-access-token",`
`"expires_in": 3600`
`}`
***
### **5.2 Core Endpoints**
#### **1. Conversational AI**
**Endpoint:** POST /ai/converse\
**Description:** Processes user inputs and generates AI responses.
**Request:**
`POST /ai/converse`
`Authorization: Bearer YOUR_API_KEY`
`Content-Type: application/json`
**Body:**
`{`
`"user_id": "12345",`
`"input": "What’s the weather like today?",`
`"context": {`
`"location": "New York"`
`}`
`}`
**Response:**
`{`
`"response": "The weather in New York is sunny with a high of 75°F.",`
`"context": {`
`"location": "New York"`
`}`
`}`
#### **2. Task Execution**
**Endpoint:** POST /tasks/execute\
**Description:** Executes tasks such as scheduling, reminders, or custom workflows.
**Request:**
`POST /tasks/execute`
`Authorization: Bearer YOUR_API_KEY`
`Content-Type: application/json`
**Body:**
`{`
`"task_type": "schedule",`
`"task_details": {`
`"title": "Meeting with Sarah",`
`"date": "2024-12-15",`
`"time": "10:00 AM",`
`"location": "Zoom"`
`}`
`}`
**Response:**
`{`
`"task_id": "abc123",`
`"status": "scheduled",`
`"details": {`
`"title": "Meeting with Sarah",`
`"date": "2024-12-15",`
`"time": "10:00 AM",`
`"location": "Zoom"`
`}`
`}`
**3. User Profile Management**
**Endpoint:** GET /users/{user\_id}\
**Description:** Retrieves user profile information.
**Request:**
`GET /users/12345`
`Authorization: Bearer YOUR_API_KEY`
**Response:**
`{`
`"user_id": "12345",`
`"name": "John Doe",`
`"email": "john.doe@example.com",`
`"preferences": {`
`"language": "en",`
`"timezone": "EST"`
`}`
`}`
#### **4. Knowledge Base Query**
**Endpoint:** POST /kb/query\
**Description:** Queries the knowledge base for domain-specific information.
**Request:**
`POST /kb/query`
`Authorization: Bearer YOUR_API_KEY`
`Content-Type: application/json`
**Body:**
`{`
`"query": "What are the top features of Ferdy?"`
`}`
**Response:**
`{`
`"result": [`
`"Generative AI for content creation",`
`"Conversational AI for natural language interactions",`
`"Voice assistance for hands-free use"`
`]`
`}`
#### **5. Voice Processing**
**Endpoint:** POST /voice/process\
**Description:** Processes audio inputs and returns transcribed text.
**Request:**
`POST /voice/process`
`Authorization: Bearer YOUR_API_KEY`
`Content-Type: multipart/form-data`
**Body:**
`{`
`"file": "audio_sample.wav"`
`}`
**Response:**
`{`
`"transcription": "What's the status of my task list?"`
`}`
***
### **5.3 Response Codes**
* 200 OK: Successful request.
* 400 Bad Request: Invalid request parameters.
* 401 Unauthorized: Invalid API key or token.
* 404 Not Found: Resource not found.
* 500 Internal Server Error: Server error.
***
### **5.4 SDK Integration**
Ferdy APIs can be accessed through SDKs for quick implementation in web and mobile apps.
#### **JavaScript Example:**
`import { FerdyAPI } from 'ferdy-sdk';`
`const ferdy = new FerdyAPI({ apiKey: 'YOUR_API_KEY' });`
`async function fetchResponse() {`
`const response = await ferdy.converse({`
`userId: '12345',`
`input: 'What’s on my schedule today?'`
`});`
`console.log(response);`
`}`
`fetchResponse();`
#### **Python Example:**
`from ferdy_sdk import FerdyClient`
`client = FerdyClient(api_key="YOUR_API_KEY")`
`response = client.converse(`
`user_id="12345",`
`input="What’s on my schedule today?"`
`)`
`print(response)`