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
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
OAuth 2.0
Generate an access token using the /auth/token endpoint.
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)
Last updated