Skip to content

API_REFERENCE.md

Latest commit

 

History

History
168 lines (99 loc) · 3.93 KB

API_REFERENCE.md

File metadata and controls

168 lines (99 loc) · 3.93 KB
Raw

Agent-X API Reference

Base URL: /api

All endpoints except POST /api/auth/login and GET /api/system/health require Authorization: Bearer <jwt_token>.

Auth

POST /api/auth/login

Login with owner password.

Body: { "password": "string" } Response: { "access_token": "string", "token_type": "bearer", "expires_in": 86400 }

System

GET /api/system/health

Public health check.

Response: { "status": "healthy", "version": "1.1.0", "timestamp": "ISO8601" }

POST /api/system/cycle/trigger

Manually trigger the full research → draft pipeline.

Response: Pipeline result object with batch_id and post count.

Posts

GET /api/posts

List posts with filtering and pagination.

Query params: status, batch_id, search, page (default 1), page_size (default 20)

Response: { "items": [Post], "total": int, "page": int, "per_page": int }

GET /api/posts/dashboard-stats

Dashboard overview statistics.

Response: { "posts_today", "posts_this_month", "pending_review", "published_total", "sources_healthy", "sources_total" }

GET /api/posts/recent-activity

Recent post activity.

Query: limit (default 10)

GET /api/posts/{post_id}

Get single post by ID.

PATCH /api/posts/{post_id}

Update post — approve, reject, edit content.

Body: { "status?": "approved|rejected", "content?": "string", "feedback?": "string", "scheduled_for?": "ISO8601" }

POST /api/posts/{post_id}/image

Upload image attachment (multipart/form-data).

Response: { "message": "string", "image_url": "string" }

POST /api/posts/{post_id}/metrics

Submit manual engagement metrics.

Body: { "impressions": int, "likes": int, "retweets": int, "replies": int }

GET /api/posts/{post_id}/metrics

Get metrics for a specific post.

POST /api/posts/fetch-metrics

Fetch metrics from X API for recently published posts.

Sources

GET /api/sources

List all content sources.

POST /api/sources

Create new source.

Body: { "name": "string", "url": "string", "source_type": "hackernews|rss", "category": "string", "is_active": true }

PATCH /api/sources/{source_id}

Update source.

DELETE /api/sources/{source_id}

Delete source.

Categories

GET /api/categories

List all categories.

POST /api/categories

Create category.

Body: { "name": "string", "is_active": true }

PATCH /api/categories/{category_id}

Update category.

Style Config

GET /api/style-config

Get active style configuration (tone, topics, hashtags, thread preference).

Response: { "id", "tone", "topics": [], "hashtag_policy": "always|never", "thread_preference": bool, "updated_at" }

Note: Stored as JSONB in DB, flattened by the API. use_hashtags → hashtag_policy, thread_style → thread_preference.

PUT /api/style-config

Update style configuration. Creates a new version.

Analytics

GET /api/analytics/overview

Aggregate engagement metrics.

Query: period (7d, 30d, all)

Response: { "post_count", "total_impressions", "total_likes", "total_reposts", "total_replies", "engagement_rate", "period" }

GET /api/analytics/categories

Per-category analytics breakdown.

Query: period (7d, 30d, all)

Improvements

GET /api/improvements

List AI-generated improvement proposals (newest first).

GET /api/improvements/{proposal_id}

Get single proposal.

PATCH /api/improvements/{proposal_id}

Approve or reject proposal.

Body: { "status": "approved|rejected" }

Settings

GET /api/settings/llm-model

Get current LLM model configuration.

Response: { "model_id": "gemini-2.0-flash", "source": "database|env" }

PUT /api/settings/llm-model

Set LLM model dynamically (persisted to database).

Body: { "model_id": "gemini-2.0-flash" }

Response: { "model_id": "gemini-2.0-flash", "message": "LLM model updated" }