# 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)`
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://feeda.gitbook.io/ferdy-framework/5.-api-reference.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.