# Audience Suite API Agent Manifest Technical reference for coding assistants and AI agents integrating with the Audience Suite REST API or MCP server. --- ## System - **Name:** Audience Suite API - **Purpose:** AI-powered audience analysis, profile creation, knowledge retrieval, and content planning. - **REST Production Base URL:** `https://api.audience-suite.de` - **REST Staging Base URL:** `https://api-staging.audience-suite.de` - **MCP Production Base URL:** `https://api.audience-suite.de/mcp` - **MCP Staging Base URL:** `https://api-staging.audience-suite.de/mcp` - **Authentication:** `Authorization: Bearer ` - **Public documentation:** `https://docs.audience-suite.de` Public API responses do not expose DynamoDB keys. Internal `PK` and `SK` fields are removed; entity IDs are exposed as `projectId`, `profileId`, `feedId`, `scheduleId`, and `jobId`. --- ## REST API ### Status - `GET /api/status` - Auth: not required. ```json { "status": "ok", "service": "audience-suite-api", "uptime": 175.883477544, "timestamp": "2026-05-03T21:44:13.065Z" } ``` ### Projects - `GET /api/projects` - Auth: required. - Response: array of project objects. ```json [ { "projectId": "proj_demo123", "type": "Project", "projectType": "files", "state": "Finished", "name": "Demo Analyseprojekt", "description": "Auswertung von Interviews und Frageboegen", "context": "", "createdAt": "2026-01-08T14:44:35.026Z", "data": { "iconColor": "bg-blue-500", "iconName": "Briefcase" }, "options": { "profileCount": 1, "files": [ { "name": "Interview 01.docx", "lastModified": 1766161526004, "size": 18159359, "type": "einzelinterview" } ] } } ] ``` ### Profiles - `GET /api/projects/:projectId/profiles` - `GET /api/projects/:projectId/profiles/:profileId` - Auth: required. ```json { "projectId": "proj_demo123", "profileId": "prof_demo456", "name": "Alex Beispiel", "beschreibung": "", "createdAt": "2026-01-08T15:15:55.876Z", "schwartz_values": { "Macht": 3, "Universalismus": 2, "Tradition": 2, "Wohltätigkeit": 5, "Selbstbestimmung": 3, "Hedonismus": 2, "Stimulation": 3, "Leistung": 3, "Konformität": 2, "Sicherheit": 3 }, "userNeeds": { "Keep me engaged": 5, "Educate me": 4, "Give me perspective": 4, "Inspire me": 3, "Help me": 4, "Connect me": 5, "Update me": 4, "Divert me": 1 }, "eigenschaften": [], "kernwerte": [], "categories": [ { "name": "Person und Kontext", "sources": ["Interview 01.docx"], "items": [ { "typ": "aussage", "text": "Legt grossen Wert auf vertraulichen Austausch." } ] } ] } ``` ### Feeds And Schedules - `GET /api/projects/:projectId/profiles/:profileId/feeds` - `GET /api/projects/:projectId/profiles/:profileId/schedules` - Auth: required. - Response: array. Empty arrays are valid. ```json [] ``` ### Knowledge Search - `GET /api/projects/:projectId/search?q=&limit=` - Auth: required. - `q`: required string. - `limit`: optional number, defaults to 5, server maximum 20. ```json [ { "id": ["chunk_demo_001"], "text": ["Relevanter Ausschnitt aus Interview oder Fragebogen."], "metadata": [ { "type": "insight", "projectId": "proj_demo123", "source": "Interview 01.docx" } ] } ] ``` When ChromaDB is unavailable: ```json { "error": "Failed to connect to chromadb. Make sure your server is running and try again." } ``` ### Jobs - `POST /api/projects/:projectId/jobs/analysis` - `POST /api/projects/:projectId/jobs/profile` - `GET /api/projects/:projectId/jobs` - `GET /api/projects/:projectId/jobs/:jobId` - Auth: required. Create endpoints use `multipart/form-data` with one or more `file` fields. Profile jobs also require `profileCount`. Create analysis response: ```json { "jobId": "job_demo001", "creditCost": 2 } ``` Create profile response: ```json { "jobId": "job_demo002", "creditCost": 10 } ``` Job object: ```json { "type": "Job", "projectId": "proj_demo123", "jobId": "job_demo001", "jobType": "file", "jobMode": "analyze-only", "status": "Finished", "creditCost": 2, "createdAt": "2026-03-15T17:18:10.994Z", "updatedAt": "2026-03-15T17:30:26.578Z", "config": { "profileCount": 0, "projectContext": "Demo-Kontext", "identityId": "eu-central-1:identity-demo", "jobMode": "analyze-only", "imageStyle": "realistic", "files": [ { "name": "Interview 01.docx", "lastModified": 1691839900000, "s3Key": "users/user_demo/projects/proj_demo123/readonly/Interview 01.docx", "size": 22271, "type": "einzelinterview" } ], "categories": [] } } ``` --- ## MCP API ### Connection - **Transport:** SSE - **Production SSE endpoint:** `https://api.audience-suite.de/mcp/sse` - **Staging SSE endpoint:** `https://api-staging.audience-suite.de/mcp/sse` - **Message endpoint:** `/mcp/messages?sessionId=` - **Auth header:** `Authorization: Bearer ` ### Tools #### Projects - `list_projects()` - Returns: JSON string containing an array of public project objects. #### Profiles - `list_profiles(projectId: string)` - `get_profile(projectId: string, profileId: string)` - Returns: JSON string containing profile object(s). #### Feeds And Schedules - `list_feeds(projectId: string, profileId: string)` - `list_schedules(projectId: string, profileId: string)` - Returns: JSON string containing an array. Empty arrays are valid. #### Knowledge - `search_knowledge(projectId: string, query: string, limit?: number)` - Returns: JSON string containing search results. - Error shape: ```json { "isError": true, "content": [ { "type": "text", "text": "Error accessing ChromaDB: ..." } ] } ``` #### Jobs - `create_analysis_job(projectId: string, files?: string[], config?: object)` - `create_profile_job(projectId: string, profileCount: number, files?: string[], config?: object)` - `list_jobs(projectId: string)` - `get_job(projectId: string, jobId: string)` MCP create-job tools expect S3 keys in `files`; REST create-job endpoints upload binary files directly. Create analysis response: ```json { "content": [ { "type": "text", "text": "Analysis job successfully created: job_demo001 (Cost: 2 credits)" } ] } ``` Create profile response: ```json { "content": [ { "type": "text", "text": "Profile creation job successfully created: job_demo002 (Cost: 10 credits)" } ] } ``` --- ## Agent Notes - Use `projectId` as the primary filter for project-scoped calls. - Use `profileId` only together with its parent `projectId`. - Use `jobId` only together with its parent `projectId`. - REST job creation uploads files via `multipart/form-data`. - MCP job creation references existing S3 object keys. - Search depends on ChromaDB availability and can return service errors if the vector database is unavailable. - Credits are required for creating jobs. - Supported analysis inputs include document, audio, video, image, spreadsheet, and questionnaire files.