API Reference

Floyi’s External API lets you access your data programmatically through a versioned REST API. Use it to connect AI agents, automate workflows with Zapier or Make, or build custom dashboards on top of your Floyi workspace.

• How to create and manage API keys
• How to authenticate API requests
• All available V1 endpoints with examples
• Permission scopes, rate limits, and error handling

Floyi uses a 4-level topical hierarchy. The API field names (used in JSON responses) differ from the display labels shown in the Floyi dashboard. Every API response includes a _meta object with the mapping, but here is the complete reference:

Node types in the authority hierarchy also use internal labels that map to the same display names:

[!IMPORTANT] Always use the display labels (Pillar, Hub, Branch, Resource) when presenting hierarchy data to users. The API field names (main_topic, subtopic_2, etc.) are internal identifiers that should not be shown in user-facing interfaces.

Every V1 API response includes a _meta object with:

• description — What this endpoint returns and how to interpret the data
• level_labels — Mapping from API field names to display labels (included on hierarchy endpoints)
• node_type_labels — Mapping from internal node types to display labels (included on authority endpoints)

Example:

{
  "_meta": {
    "description": "Returns the full 4-level topical hierarchy...",
    "level_labels": {
      "main_topic": "Pillar",
      "subtopic_2": "Hub",
      "subtopic_3": "Branch",
      "subtopic_4": "Resource"
    }
  },
  "brand_id": "...",
  "research_data": [...]
}

Floyi’s API supports two content generation workflows:

[!TIP] Which should I use? If you have a topical map and want briefs/articles tracked in the Planner tab, use the Authority endpoints. If you want to generate a quick brief for any topic without hierarchy linkage, use the Standalone endpoints.

Floyi provides machine-readable API documentation for developer tools, AI coding assistants, and automation platforms.

The OpenAPI schema can be imported directly into tools like Postman or Insomnia to auto-generate request templates. AI coding assistants (Claude, ChatGPT, Cursor, etc.) can read the llms-full.txt file to understand the full API without needing authentication.

[!NOTE] The External API is currently in beta. Access is limited to approved users. Contact support to request access.

API key creation requires an Agency plan. If you are on the Free, Creator, or Pro plan, the API Keys tab in Settings will prompt you to upgrade.

1. Go to Settings > API Keys.
2. Click Create API Key.
3. Enter a name for the key (e.g., “My AI Agent” or “Zapier Integration”).
4. Choose a key type (see Key Types below).
5. Review and customize permissions if needed.
6. Click Create.
7. Copy the API key immediately. It is shown only once and cannot be retrieved later.

[!IMPORTANT] Store your API key securely. Treat it like a password. Never commit it to version control, share it in chat, or expose it in client-side code.

All Floyi API keys follow the format:

fyi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The fyi_live_ prefix identifies Floyi keys in logs and secret scanners. The full key is 44 characters.

Every API request must include your key in the X-API-Key header.

For POST, PUT, and PATCH requests, you must also set the Content-Type: application/json header and send a JSON request body.

# GET request (read)
curl -H "X-API-Key: fyi_live_your_key_here" \
  https://api.floyi.com/api/v1/brands/

# POST request (write)
curl -X POST \
  -H "X-API-Key: fyi_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"brand_name": "My Brand"}' \
  https://api.floyi.com/api/v1/brands/

import requests

API_KEY = "fyi_live_your_key_here"
BASE_URL = "https://api.floyi.com/api/v1"
headers = {"X-API-Key": API_KEY}

# GET request (read)
response = requests.get(f"{BASE_URL}/brands/", headers=headers)
brands = response.json()

# POST request (write)
response = requests.post(
    f"{BASE_URL}/brands/",
    headers=headers,
    json={"brand_name": "My Brand"},
)
new_brand = response.json()

const API_KEY = "fyi_live_your_key_here";
const BASE_URL = "https://api.floyi.com/api/v1";
const headers = { "X-API-Key": API_KEY };

// GET request (read)
const brandsRes = await fetch(`${BASE_URL}/brands/`, { headers });
const brands = await brandsRes.json();

// POST request (write)
const createRes = await fetch(`${BASE_URL}/brands/`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ brand_name: "My Brand" }),
});
const newBrand = await createRes.json();

A 401 response includes a description in the response body:

{
  "detail": "Invalid API key."
}

Possible messages: "Invalid API key.", "API key has expired.", "API key has been revoked.", "User account is no longer active.", "Request from unauthorized IP address.", "The External API is currently in beta. Contact support to request access."

A 403 response means the key is valid but lacks the required scope:

{
  "detail": "You do not have permission to perform this action."
}

Check your key’s assigned scopes in Settings > API Keys and ensure they include the scope listed for the endpoint you are calling (e.g., briefs:write for brief generation).

API keys are account-level — they are not tied to a specific workspace. To control which workspace your request operates on, use the optional X-Team-ID header.

Discovering your team UUIDs:

Call the /api/v1/me/teams/ endpoint to list all teams you are an active member of. Each team object includes the id (UUID) you need for the X-Team-ID header.

curl -H "X-API-Key: fyi_live_your_key_here" \
  https://api.floyi.com/api/v1/me/teams/

{
  "_meta": { "description": "Lists all teams the authenticated user is an active member of..." },
  "results": [
    {
      "team": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Acme Marketing",
        "slug": "acme-marketing",
        "plan_name": "Agency Plan",
        "created_at": "2025-09-15T10:00:00Z"
      },
      "role": "owner",
      "status": "active"
    }
  ]
}

Using the team UUID in requests:

# Personal workspace (no header)
curl -H "X-API-Key: fyi_live_your_key_here" \
  https://api.floyi.com/api/v1/brands/

# Team workspace
curl -H "X-API-Key: fyi_live_your_key_here" \
  -H "X-Team-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  https://api.floyi.com/api/v1/brands/

# Personal workspace (no header)
response = requests.get(f"{BASE_URL}/brands/", headers=headers)

# Team workspace
team_headers = {**headers, "X-Team-ID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}
response = requests.get(f"{BASE_URL}/brands/", headers=team_headers)

// Personal workspace (no header)
const res = await fetch(`${BASE_URL}/brands/`, { headers });

// Team workspace
const teamHeaders = { ...headers, "X-Team-ID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" };
const teamRes = await fetch(`${BASE_URL}/brands/`, { headers: teamHeaders });

[!TIP] You can use the same API key for both personal and team workspaces. The X-Team-ID header is the only thing that determines which workspace a request operates on. You can access any team where you are an active member.

Each API key has a set of permission scopes that control which endpoints it can access. You can customize scopes when creating a key.

Rate limits are applied per key based on the key type.

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.

{
  "detail": "Request was throttled. Expected available in 12 seconds."
}

All endpoints are under /api/v1/. Responses are JSON. List endpoints return arrays of objects. Detail endpoints return a single object.

Scope required: brands:read (GET), brands:write (POST)

GET /api/v1/brands/

Returns all brands in your workspace, ordered by most recently created.

Query parameters:

curl -H "X-API-Key: fyi_live_your_key_here" \
  https://api.floyi.com/api/v1/brands/

# Search by name
curl -H "X-API-Key: fyi_live_your_key_here" \
  "https://api.floyi.com/api/v1/brands/?search=floyi"

response = requests.get(f"{BASE_URL}/brands/", headers=headers)
brands = response.json()

# Search by name
response = requests.get(
    f"{BASE_URL}/brands/",
    headers=headers,
    params={"search": "floyi"},
)

const res = await fetch(`${BASE_URL}/brands/`, { headers });
const brands = await res.json();

// Search by name
const searchRes = await fetch(`${BASE_URL}/brands/?search=floyi`, { headers });

Response:

[
  {
    "id": "a1b2c3d4-...",
    "brand_name": "Floyi",
    "website_url": "https://floyi.com",
    "mission": "...",
    "vision": "...",
    "tagline": "...",
    "target_audience": "...",
    "brand_voice": "...",
    "values": "...",
    "marketplace": "...",
    "market_position": "...",
    "key_competitors": "...",
    "unique_selling_proposition": "...",
    "brand_personality": "...",
    "brand_story": "...",
    "language": "en",
    "country_code": "US",
    "country_name": "United States",
    "stage": "completed",
    "content_scope": "...",
    "created_at": "2026-02-01T10:00:00Z",
    "updated_at": "2026-02-15T14:30:00Z"
  }
]

GET /api/v1/brands/{id}/

Returns full details for a single brand. The response shape is the same as each object in the list endpoint. Returns 404 if the brand is not found or you do not have access.

curl -H "X-API-Key: fyi_live_your_key_here" \
  https://api.floyi.com/api/v1/brands/a1b2c3d4-.../

brand_id = "a1b2c3d4-..."
response = requests.get(f"{BASE_URL}/brands/{brand_id}/", headers=headers)
brand = response.json()

const brandId = "a1b2c3d4-...";
const res = await fetch(`${BASE_URL}/brands/${brandId}/`, { headers });
const brand = await res.json();

Response:

{
  "id": "a1b2c3d4-...",
  "brand_name": "Floyi",
  "website_url": "https://floyi.com",
  "mission": "...",
  "vision": "...",
  "tagline": "...",
  "target_audience": "...",
  "brand_voice": "...",
  "values": "...",
  "marketplace": "...",
  "market_position": "...",
  "key_competitors": "...",
  "unique_selling_proposition": "...",
  "brand_personality": "...",
  "brand_story": "...",
  "language": "en",
  "country_code": "US",
  "country_name": "United States",
  "stage": "completed",
  "content_scope": "...",
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-15T14:30:00Z"
}

POST /api/v1/brands/

Request body:

{
  "brand_name": "My New Brand",
  "website_url": "https://example.com",
  "mission": "Help teams create better content",
  "target_audience": "Content marketers and SEO professionals",
  "language": "en"
}

Required fields: brand_name

Optional fields: website_url, mission, vision, tagline, target_audience, brand_voice, values, marketplace, key_competitors, unique_selling_proposition, description, language

curl -X POST \
  -H "X-API-Key: fyi_live_your_integration_key" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_name": "My New Brand",
    "website_url": "https://example.com",
    "mission": "Help teams create better content",
    "target_audience": "Content marketers and SEO professionals",
    "language": "en"
  }' \
  https://api.floyi.com/api/v1/brands/

response = requests.post(
    f"{BASE_URL}/brands/",
    headers=headers,
    json={
        "brand_name": "My New Brand",
        "website_url": "https://example.com",
        "mission": "Help teams create better content",
        "target_audience": "Content marketers and SEO professionals",
        "language": "en",
    },
)
brand = response.json()

const res = await fetch(`${BASE_URL}/brands/`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    brand_name: "My New Brand",
    website_url: "https://example.com",
    mission: "Help teams create better content",
    target_audience: "Content marketers and SEO professionals",
    language: "en",
  }),
});
const brand = await res.json();

Response (201 Created):

{
  "id": "a1b2c3d4-...",
  "brand_name": "My New Brand",
  "website_url": "https://example.com",
  "mission": "Help teams create better content",
  "vision": null,
  "tagline": null,
  "target_audience": "Content marketers and SEO professionals",
  "brand_voice": null,
  "values": null,
  "marketplace": null,
  "market_position": null,
  "key_competitors": null,
  "unique_selling_proposition": null,
  "brand_personality": null,
  "brand_story": null,
  "language": "en",
  "country_code": null,
  "country_name": null,
  "stage": "new",
  "content_scope": null,
  "created_at": "2026-02-22T10:00:00Z",
  "updated_at": "2026-02-22T10:00:00Z"
}

The response returns the full brand object, including the id you need for subsequent API calls (briefs, maps, articles).

Error responses:

{
  "brand_name": ["This field is required."]
}

Scope required: briefs:read (GET), briefs:write (POST)

GET /api/v1/briefs/

Returns all content briefs in your workspace.

Query parameters:

curl -H "X-API-Key: fyi_live_your_key_here" \
  "https://api.floyi.com/api/v1/briefs/?brand_id=a1b2c3d4-..."

# Search by topic name
curl -H "X-API-Key: fyi_live_your_key_here" \
  "https://api.floyi.com/api/v1/briefs/?search=what+is+topical+authority"

response = requests.get(
    f"{BASE_URL}/briefs/",
    headers=headers,
    params={"brand_id": "a1b2c3d4-..."},
)
briefs = response.json()

# Search by topic name
response = requests.get(
    f"{BASE_URL}/briefs/",
    headers=headers,
    params={"search": "what is topical authority"},
)

const res = await fetch(
  `${BASE_URL}/briefs/?brand_id=a1b2c3d4-...`,
  { headers },
);
const briefs = await res.json();

// Search by topic name
const searchRes = await fetch(
  `${BASE_URL}/briefs/?search=what+is+topical+authority`,
  { headers },
);

Response:

[
  {
    "id": "b5c6d7e8-...",
    "query_text": "best seo tools for agencies",
    "brand_name": "Floyi",
    "status": "COMPLETE",
    "generated_title": "Best SEO Tools for Agencies in 2026",
    "generated_meta_description": "Discover the top SEO tools...",
    "created_at": "2026-02-10T08:00:00Z",
    "updated_at": "2026-02-10T08:15:00Z"
  }
]

GET /api/v1/briefs/{id}/

Returns the full brief including the complete result_json and curated_brief_json with all SERP analysis, competitor data, headings, and recommendations. Returns 404 if the brief is not found or you do not have access.

curl -H "X-API-Key: fyi_live_your_key_here" \
  https://api.floyi.com/api/v1/briefs/b5c6d7e8-.../

brief_id = "b5c6d7e8-..."
response = requests.get(f"{BASE_URL}/briefs/{brief_id}/", headers=headers)
brief = response.json()

const briefId = "b5c6d7e8-...";
const res = await fetch(`${BASE_URL}/briefs/${briefId}/`, { headers });
const brief = await res.json();

Response:

{
  "id": "b5c6d7e8-...",
  "query_text": "best seo tools for agencies",
  "brand_name": "Floyi",
  "status": "COMPLETE",
  "generated_title": "Best SEO Tools for Agencies in 2026",
  "generated_meta_description": "Discover the top SEO tools...",
  "result_json": {
    "header_sections": [ ... ],
    "serp_analysis": { ... },
    "competitor_data": [ ... ],
    "keyword_recommendations": [ ... ]
  },
  "curated_brief_json": {
    "header_sections": [ ... ],
    "meta_title": "...",
    "meta_description": "..."
  },
  "input_params": {
    "query_text": "best seo tools for agencies",
    "brand_id": "a1b2c3d4-...",
    "selected_serp_data": [ ... ]
  },
  "created_at": "2026-02-10T08:00:00Z",
  "updated_at": "2026-02-10T08:15:00Z"
}

Detail-only fields (not included in the list endpoint):

[!NOTE] The result_json and curated_brief_json fields contain complex nested structures produced by the brief generation agent. The exact shape may vary, but both always include a header_sections array representing the content outline.

GET /api/v1/briefs/{id}/status/

Returns just the status of a brief. Useful for polling during brief generation.

curl -H "X-API-Key: fyi_live_your_key_here" \
  https://api.floyi.com/api/v1/briefs/b5c6d7e8-.../status/

brief_id = "b5c6d7e8-..."
response = requests.get(f"{BASE_URL}/briefs/{brief_id}/status/", headers=headers)
status = response.json()

const briefId = "b5c6d7e8-...";
const res = await fetch(`${BASE_URL}/briefs/${briefId}/status/`, { headers });
const status = await res.json();

Response:

{
  "id": "b5c6d7e8-...",
  "status": "COMPLETE",
  "query_text": "best seo tools for agencies",
  "generated_title": "Best SEO Tools for Agencies in 2026"
}

Status values:

[!TIP] When polling, treat COMPLETE and PARTIAL_COMPLETE as terminal success states, and FAILED as a terminal error state. All other statuses indicate the brief is still in progress.

POST /api/v1/briefs/generate/

Triggers standalone content brief generation for any topic. This is a freeform endpoint — you provide the topic text directly. For hierarchy-linked briefs (tied to your topical authority map), use the Authority Briefs endpoints instead.

Returns immediately with a 202 Accepted response. Poll the status endpoint for progress.

Request body:

{
  "query_text": "best seo tools for agencies",
  "brand_id": "a1b2c3d4-...",
  "ai_model_id": "gpt-5-mini"
}

Required fields: query_text, brand_id

Optional fields:

# Minimal
curl -X POST \
  -H "X-API-Key: fyi_live_your_integration_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query_text": "best seo tools for agencies",
    "brand_id": "a1b2c3d4-..."
  }' \
  https://api.floyi.com/api/v1/briefs/generate/

# With SERP data and keywords
curl -X POST \
  -H "X-API-Key: fyi_live_your_integration_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query_text": "best seo tools for agencies",
    "brand_id": "a1b2c3d4-...",
    "selected_serp_data": [
      {"url": "https://example.com", "title": "Example", "snippet": "..."}
    ],
    "user_provided_keywords": ["seo software", "agency tools"]
  }' \
  https://api.floyi.com/api/v1/briefs/generate/

# Minimal
response = requests.post(
    f"{BASE_URL}/briefs/generate/",
    headers=headers,
    json={
        "query_text": "best seo tools for agencies",
        "brand_id": "a1b2c3d4-...",
    },
)
brief = response.json()

# With SERP data and keywords
response = requests.post(
    f"{BASE_URL}/briefs/generate/",
    headers=headers,
    json={
        "query_text": "best seo tools for agencies",
        "brand_id": "a1b2c3d4-...",
        "selected_serp_data": [
            {"url": "https://example.com", "title": "Example", "snippet": "..."}
        ],
        "user_provided_keywords": ["seo software", "agency tools"],
    },
)

// Minimal
const res = await fetch(`${BASE_URL}/briefs/generate/`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    query_text: "best seo tools for agencies",
    brand_id: "a1b2c3d4-...",
  }),
});
const brief = await res.json();

// With SERP data and keywords
const res2 = await fetch(`${BASE_URL}/briefs/generate/`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    query_text: "best seo tools for agencies",
    brand_id: "a1b2c3d4-...",
    selected_serp_data: [
      { url: "https://example.com", title: "Example", snippet: "..." },
    ],
    user_provided_keywords: ["seo software", "agency tools"],
  }),
});

Response (202 Accepted):

{
  "id": "b5c6d7e8-...",
  "status": "PENDING",
  "query_text": "best seo tools for agencies",
  "brand_name": "Floyi",
  "message": "Brief generation started. Poll /api/v1/briefs/{id}/status/ for progress."
}

[!TIP] After generating a brief, poll GET /api/v1/briefs/{id}/status/ every 10-15 seconds until the status changes to COMPLETE. Brief generation typically takes 1-3 minutes depending on the number of SERP pages to analyze.

Error responses:

400 — No SERP data available (auto-fetch):

When selected_serp_data is omitted, the API attempts to auto-fetch cached SERP data for the topic from the brand’s topical map. If no cached SERP data exists for that keyword, the request fails with a 400:

{
  "detail": "No SERP data available for this topic. Please provide selected_serp_data or ensure SERP data has been collected for this topic in the topical map."
}

To resolve this, either:

1. Provide selected_serp_data manually with competitor pages you want analyzed, or
2. Ensure SERP data has been collected for this topic in the topical map first (via the Floyi dashboard)

400 — SERP entry missing url:

{
  "detail": "selected_serp_data[0] must include a 'url' field."
}

402 — Insufficient credits:

{
  "detail": "Insufficient credits."
}

404 — Brand not found:

{
  "detail": "Brand not found or you do not have access."
}

[!NOTE] Standalone briefs are not linked to the authority hierarchy. If you need briefs tied to specific topics in your topical map (for the Planner tab), use POST /api/v1/authority/{brand_id}/briefs/generate/ instead.

Scope required: content:read (GET), content:write (POST)

GET /api/v1/content/articles/

Returns all content articles in your workspace.

Query parameters:

curl -H "X-API-Key: fyi_live_your_key_here" \
  "https://api.floyi.com/api/v1/content/articles/?brand_id=a1b2c3d4-..."

# Search by title
curl -H "X-API-Key: fyi_live_your_key_here" \
  "https://api.floyi.com/api/v1/content/articles/?search=seo+tools"

response = requests.get(
    f"{BASE_URL}/content/articles/",
    headers=headers,
    params={"brand_id": "a1b2c3d4-..."},
)
articles = response.json()

# Search by title
response = requests.get(
    f"{BASE_URL}/content/articles/",
    headers=headers,
    params={"search": "seo tools"},
)

const res = await fetch(
  `${BASE_URL}/content/articles/?brand_id=a1b2c3d4-...`,
  { headers },
);
const articles = await res.json();

// Search by title
const searchRes = await fetch(
  `${BASE_URL}/content/articles/?search=seo+tools`,
  { headers },
);

Response:

[
  {
    "id": "c7d8e9f0-...",
    "title": "Best SEO Tools for Agencies in 2026",
    "brand_id": "a1b2c3d4-...",
    "brand_name": "Floyi",
    "machine_state": "completed",
    "editorial_state": "draft",
    "created_at": "2026-02-12T09:00:00Z",
    "updated_at": "2026-02-14T11:00:00Z"
  }
]

GET /api/v1/content/articles/{id}/

Returns the full article including brief_id, additional_directions, and all metadata. Returns 404 if the article is not found or you do not have access.

Response:

{
  "id": "c7d8e9f0-...",
  "title": "Best SEO Tools for Agencies in 2026",
  "brand_id": "a1b2c3d4-...",
  "brand_name": "Floyi",
  "brief_id": "b5c6d7e8-...",
  "machine_state": "completed",
  "editorial_state": "draft",
  "additional_directions": "Focus on enterprise pricing tiers and team collaboration features.",
  "created_at": "2026-02-12T09:00:00Z",
  "updated_at": "2026-02-14T11:00:00Z"
}

Detail-only fields (not included in the list endpoint):

POST /api/v1/content/articles/generate/

Creates a new article from a completed content brief and immediately starts AI draft generation — one step instead of two. The brief must be in COMPLETE or PARTIAL_COMPLETE status and have generated sections.

Request body:

{
  "brief_id": "b5c6d7e8-...",
  "ai_model_id": "claude-sonnet-4",
  "intent": "human",
  "specialists": {
    "web_research": true,
    "fact_check": true,
    "intro_key_takeaways": true,
    "web_research_mode": "basic"
  }
}

Required fields: brief_id, ai_model_id

Optional fields:

Specialist agents:

[!NOTE] Specialist availability depends on the article type. Resource pages (blog posts, guides) can use web_research, fact_check, and intro_key_takeaways. Local/landing pages automatically get conversion_coach enabled. The API filters specialists to match the article type.

curl -X POST \
  -H "X-API-Key: fyi_live_your_integration_key" \
  -H "Content-Type: application/json" \
  -d '{"brief_id": "b5c6d7e8-...", "ai_model_id": "claude-sonnet-4"}' \
  https://api.floyi.com/api/v1/content/articles/generate/

response = requests.post(
    f"{BASE_URL}/content/articles/generate/",
    headers=headers,
    json={
        "brief_id": "b5c6d7e8-...",
        "ai_model_id": "claude-sonnet-4",
    },
)
article = response.json()
# article["id"] -> use for status polling

const res = await fetch(`${BASE_URL}/content/articles/generate/`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    brief_id: "b5c6d7e8-...",
    ai_model_id: "claude-sonnet-4",
  }),
});
const article = await res.json();
// article.id -> use for status polling

Response (202 Accepted):

{
  "id": "c7d8e9f0-...",
  "brief_id": "b5c6d7e8-...",
  "title": "Best SEO Tools for Agencies in 2026",
  "task_id": "e1f2a3b4-...",
  "status": "generating",
  "message": "Article created and draft generation started. Poll /api/v1/content/articles/{id}/status/ for progress."
}

[!TIP] After triggering generation, poll GET /api/v1/content/articles/{id}/status/ every 15-30 seconds. Draft generation typically takes 3-10 minutes depending on the number of sections and specialists enabled.

Error responses:

POST /api/v1/content/articles/{id}/generate/

Regenerates draft for an existing article. Creates a new version, re-syncs sections from the brief, resets all sections, and generates fresh content. Optionally accepts a different brief_id to switch briefs.

Request body:

{
  "ai_model_id": "claude-sonnet-4",
  "brief_id": "b5c6d7e8-...",
  "intent": "human",
  "specialists": {
    "web_research": true,
    "fact_check": true,
    "intro_key_takeaways": true,
    "web_research_mode": "basic"
  }
}

Required fields: ai_model_id

Optional fields: brief_id (switch to a different brief), intent, specialists

curl -X POST \
  -H "X-API-Key: fyi_live_your_integration_key" \
  -H "Content-Type: application/json" \
  -d '{"ai_model_id": "claude-sonnet-4"}' \
  https://api.floyi.com/api/v1/content/articles/c7d8e9f0-.../generate/

article_id = "c7d8e9f0-..."
response = requests.post(
    f"{BASE_URL}/content/articles/{article_id}/generate/",
    headers=headers,
    json={"ai_model_id": "claude-sonnet-4"},
)
result = response.json()

const articleId = "c7d8e9f0-...";
const res = await fetch(
  `${BASE_URL}/content/articles/${articleId}/generate/`,
  {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ ai_model_id: "claude-sonnet-4" }),
  },
);
const result = await res.json();

Response (202 Accepted):

{
  "id": "c7d8e9f0-...",
  "brief_id": "b5c6d7e8-...",
  "title": "Best SEO Tools for Agencies in 2026",
  "task_id": "e1f2a3b4-...",
  "status": "regenerating",
  "message": "Draft regeneration started. Poll /api/v1/content/articles/{id}/status/ for progress."
}

Error responses:

409 — Already in progress:

{
  "detail": "Article generation already in progress."
}

402 — Insufficient credits:

{
  "detail": "Insufficient credits."
}

GET /api/v1/content/articles/{id}/status/

Returns the current generation progress of an article. Useful for polling during draft generation.

curl -H "X-API-Key: fyi_live_your_key_here" \
  https://api.floyi.com/api/v1/content/articles/c7d8e9f0-.../status/

article_id = "c7d8e9f0-..."
response = requests.get(
    f"{BASE_URL}/content/articles/{article_id}/status/",
    headers=headers,
)
status = response.json()

const articleId = "c7d8e9f0-...";
const res = await fetch(
  `${BASE_URL}/content/articles/${articleId}/status/`,
  { headers },
);
const status = await res.json();

Response:

{
  "id": "c7d8e9f0-...",
  "machine_state": "in_progress",
  "sections_total": 8,
  "sections_approved": 3,
  "sections_drafting": 2,
  "sections_not_started": 3,
  "sections_needs_attention": 0,
  "completion_percentage": 37.5,
  "specialists_running": true,
  "specialists_complete": false
}

Machine state values:

[!TIP] When polling, treat draft_done as the terminal success state. Once complete, fetch the full article with GET /api/v1/content/articles/{id}/ to see the final content.

Scope required: maps:read

Returns the raw topical map data as created during keyword research and clustering, before any Topical Authority overrides are applied. For the enriched authority view (with organizer edits, SERP rankings, importance scores, and AI search presence), use the Topical Authority endpoints instead.

GET /api/v1/maps/

Returns all topical maps in your workspace.

Query parameters:

curl -H "X-API-Key: fyi_live_your_key_here" \
  https://api.floyi.com/api/v1/maps/

# Filter by brand
curl -H "X-API-Key: fyi_live_your_key_here" \
  "https://api.floyi.com/api/v1/maps/?brand_id=a1b2c3d4-..."

response = requests.get(f"{BASE_URL}/maps/", headers=headers)
maps = response.json()

# Filter by brand
response = requests.get(
    f"{BASE_URL}/maps/",
    headers=headers,
    params={"brand_id": "a1b2c3d4-..."},
)

const res = await fetch(`${BASE_URL}/maps/`, { headers });
const maps = await res.json();

// Filter by brand
const filteredRes = await fetch(
  `${BASE_URL}/maps/?brand_id=a1b2c3d4-...`,
  { headers },
);

Response:

[
  {
    "brand_id": "a1b2c3d4-...",
    "brand_name": "Floyi",
    "is_uploaded": false,
    "created_at": "2026-01-20T12:00:00Z",
    "updated_at": "2026-02-18T16:00:00Z"
  }
]

GET /api/v1/maps/{brand_id}/

Returns the full raw keyword clusters from the topical map, including all search metrics, SERP analysis, and content metadata. Each cluster contains its centroid keyword and all associated keywords with their complete data. Returns 404 if no map exists for this brand or you do not have access.

curl -H "X-API-Key: fyi_live_your_key_here" \
  https://api.floyi.com/api/v1/maps/a1b2c3d4-.../

brand_id = "a1b2c3d4-..."
response = requests.get(
    f"{BASE_URL}/maps/{brand_id}/", headers=headers
)
map_data = response.json()

const brandId = "a1b2c3d4-...";
const res = await fetch(`${BASE_URL}/maps/${brandId}/`, { headers });
const mapData = await res.json();

Response:

{
  "brand_id": "a1b2c3d4-...",
  "brand_name": "Floyi",
  "is_uploaded": false,
  "cluster_count": 85,
  "clusters": [
    {
      "id": "c1d2e3f4-...",
      "centroid": "best keyword research tools",
      "keyword_count": 3,
      "keywords": [
        {
          "keyword": "best keyword research tools",
          "main_topic": "SEO Strategy",
          "subtopic_2": "Keyword Research",
          "subtopic_3": "Keyword Tools",
          "subtopic_4": "best keyword research tools",
          "sort_order": 0,
          "search_volume": 2400,
          "cpc": 3.50,
          "competition": 0.72,
          "url_slug": "best-keyword-research-tools",
          "has_serp_data": true,
          "serp_analysis": "Informational listicle format dominates...",
          "serp_competitors": "ahrefs.com, semrush.com, moz.com",
          "serp_freshness": "2025-12",
          "content_title": "Best Keyword Research Tools",
          "search_intent": "informational",
          "buyers_journey": "consideration",
          "content_type": "listicle",
          "snippet": "Discover the top keyword research tools...",
          "similarity": 0.95
        }
      ]
    }
  ],
  "created_at": "2026-01-20T12:00:00Z",
  "updated_at": "2026-02-18T16:00:00Z"
}

Cluster fields:

Keyword fields — Hierarchy:

Keyword fields — Search Metrics:

Keyword fields — SERP Data:

Keyword fields — Content & URL:

[!TIP] This returns the original keyword research data. If the user has made edits in Floyi’s Organizer (renames, moves, combines), those changes are not reflected here. Use the Topical Authority endpoints to see the current effective hierarchy with all edits applied.

Scope required: research:read (GET), research:write (PATCH/POST)

Access the pre-clustering topical research tree — the 4-level topic hierarchy (Main Topics > Subtopic 2 > Subtopic 3 > Subtopic 4 > Keywords) that users build during the research phase before clustering into a topical map. These endpoints support both reading the tree and making atomic modifications (rename, add, delete, move, merge, keyword updates).

GET /api/v1/research/

Returns all topical research records in your workspace.

curl -H "X-API-Key: fyi_live_your_key_here" \
  https://api.floyi.com/api/v1/research/

response = requests.get(f"{BASE_URL}/research/", headers=headers)
records = response.json()

const res = await fetch(`${BASE_URL}/research/`, { headers });
const records = await res.json();

Response:

[
  {
    "brand_id": "a1b2c3d4-...",
    "brand_name": "Floyi",
    "core_topic": "content strategy",
    "created_at": "2026-02-01T10:00:00Z",
    "updated_at": "2026-02-20T14:30:00Z"
  }
]

GET /api/v1/research/{brand_id}/

Returns the full 4-level topic hierarchy with computed stats and generation status. Returns 404 if no research data exists for this brand.

curl -H "X-API-Key: fyi_live_your_key_here" \
  https://api.floyi.com/api/v1/research/{BRAND_ID}/

brand_id = "a1b2c3d4-..."
response = requests.get(
    f"{BASE_URL}/research/{brand_id}/", headers=headers
)
tree = response.json()

const brandId = "a1b2c3d4-...";
const res = await fetch(`${BASE_URL}/research/${brandId}/`, { headers });
const tree = await res.json();

Response:

{
  "brand_id": "a1b2c3d4-...",
  "brand_name": "Floyi",
  "core_topic": "content strategy",
  "research_data": [
    {
      "main_topic": "email marketing",
      "subtopic_2": [
        {
          "name": "email automation",
          "subtopic_3": [...],
          "subtopic_4": [],
          "keywords": []
        }
      ],
      "subtopic_3": [],
      "subtopic_4": [],
      "keywords": []
    }
  ],
  "stats": {
    "main_topic_count": 5,
    "st2_count": 23,
    "st3_count": 67,
    "st4_count": 142,
    "keyword_count": 890,
    "leaf_nodes_without_keywords": 12,
    "total_nodes": 237
  },
  "generation_status": {
    "has_running_task": false
  },
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-20T14:30:00Z"
}