DevIdeas API Reference

This page is the complete reference for the DevIdeas API. It is intended to be read by AI agents to understand how to create, read, and manage development feature trees on ratanon.com.

After reading this document, an AI should be able to accept a plain-language description of a software system from a user and immediately call the API to create a structured feature tree — without any further explanation.

1. Overview

DevIdeas stores software ideas as hierarchical feature trees. Structure: Project → Feature → Sub-feature → ... (unlimited depth). Each node has a title, description, type tag, optional resources and code snippets.

The primary use case: a user describes a software system → AI calls POST with markdown → the system parses it into a tree → the tree is publicly visible at https://ratanon.com/ideas/{slug}.

2. Authentication

All write endpoints require a Bearer token in the Authorization header.

Header

Authorization: Bearer devideas_a1fa233197d5a698da256a7b0e20c71f3816ad44f134a313d694aec0fd6835bf

Read endpoints (GET /api/ai/ideas) also require the key.

3. Endpoints

GET https://ratanon.com/api/ai/capabilities

Returns this system's full JSON documentation. Call this first if unsure of any detail.

curl

curl https://ratanon.com/api/ai/capabilities \
  -H "Authorization: Bearer devideas_a1fa233197d5a698da256a7b0e20c71f3816ad44f134a313d694aec0fd6835bf"

GET https://ratanon.com/api/ai/ideas

List all active projects (slug, title, id).

curl

curl https://ratanon.com/api/ai/ideas \
  -H "Authorization: Bearer devideas_a1fa233197d5a698da256a7b0e20c71f3816ad44f134a313d694aec0fd6835bf"

response

{
  "success": true,
  "data": [
    { "id": "uuid", "slug": "pharmacy-system", "title": "Pharmacy System", "status": "active" },
    ...
  ]
}

GET https://ratanon.com/api/ai/ideas?project={slug}

Get a specific project with its full feature tree.

curl

curl "https://ratanon.com/api/ai/ideas?project=pharmacy-system" \
  -H "Authorization: Bearer devideas_a1fa233197d5a698da256a7b0e20c71f3816ad44f134a313d694aec0fd6835bf"

response

{
  "success": true,
  "data": {
    "project": { "id": "uuid", "slug": "pharmacy-system", "title": "...", "techStack": "[...]" },
    "features": [
      {
        "id": "uuid", "title": "ระบบร้านขายยา", "type": "system",
        "description": "...", "parentId": "",
        "children": [
          {
            "id": "uuid", "title": "จัดการสินค้า", "type": "system",
            "children": [ ... ]
          }
        ]
      }
    ],
    "stats": { "total": 41, "completed": 0 }
  }
}

POST https://ratanon.com/api/ai/ideas

Create features from markdown. Auto-creates the project if projectSlug does not exist. Markdown headers become the tree hierarchy. Type tags [type:system] are parsed from header text.

Request body

{
  "projectSlug":  "string  (required)  — lowercase, hyphens only, e.g. 'pharmacy-system'",
  "markdown":     "string  (required)  — hierarchical markdown, see Section 4",
  "techStack":    ["string"]  (optional)  — e.g. ['Next.js', 'TypeScript', 'SQLite']",
  "parentId":     "string  (optional)  — UUID of an existing feature to nest under",
  "options": {
    "defaultType":       "feature | system | api | ui | database | security | devops | other",
    "extractCodeBlocks": "boolean (default: true)",
    "extractLinks":      "boolean (default: true)"
  }
}

curl example

curl -X POST https://ratanon.com/api/ai/ideas \
  -H "Authorization: Bearer devideas_a1fa233197d5a698da256a7b0e20c71f3816ad44f134a313d694aec0fd6835bf" \
  -H "Content-Type: application/json" \
  -d '{
    "projectSlug": "todo-app",
    "techStack": ["Next.js", "TypeScript", "PostgreSQL"],
    "markdown": "# Todo App [type:system]\nTask management app\n\n## Authentication [type:security]\nJWT login\n\n### Login [type:api]\nPOST /api/auth/login\n\n### Register [type:api]\nPOST /api/auth/register\n\n## Tasks [type:system]\nCRUD for tasks\n\n### Create Task [type:feature]\nAdd new task with title, due date, priority\n\n### Task List [type:ui]\nPaginated list with filter and sort"
  }'

response

{
  "success": true,
  "data": {
    "project": { "id": "uuid", "slug": "todo-app", "isNew": true },
    "imported": { "topLevel": 1, "total": 7 },
    "features": [ ... parsed tree ... ]
  },
  "message": "Successfully imported 7 features"
}

PUT https://ratanon.com/api/ai/ideas

Update a single feature by ID. Useful to add descriptions, code snippets, or fix types.

{
  "featureId": "uuid  (required)",
  "updates": {
    "title":       "string (optional)",
    "description": "string (optional)  — supports markdown",
    "type":        "system | feature | api | ui | database | security | devops | other",
    "status":      "pending | in_progress | completed | archived",
    "codeSnippet": "string (optional)",
    "notes":       "string (optional)  — private notes, not shown publicly"
  }
}

curl example

curl -X PUT https://ratanon.com/api/ai/ideas \
  -H "Authorization: Bearer devideas_a1fa233197d5a698da256a7b0e20c71f3816ad44f134a313d694aec0fd6835bf" \
  -H "Content-Type: application/json" \
  -d '{
    "featureId": "60815569-ee2a-4bec-a83f-be4dd4a1058b",
    "updates": {
      "description": "ระบบจองโต๊ะร้านอาหาร รองรับ walk-in และ online booking",
      "codeSnippet": "interface Booking { id: string; tableId: string; date: Date; }"
    }
  }'

DELETE https://ratanon.com/api/ai/ideas?featureId={uuid}

Delete a feature and all its children.

curl

curl -X DELETE "https://ratanon.com/api/ai/ideas?featureId=uuid" \
  -H "Authorization: Bearer devideas_a1fa233197d5a698da256a7b0e20c71f3816ad44f134a313d694aec0fd6835bf"

4. Markdown Format

The POST endpoint parses markdown headers into a tree. Depth comes from heading level (# = root, ## = level 2, etc.). Type is set with a tag [type:xxx] at the end of the heading line. If no tag is given, feature is used as default.

Syntax

# System Name [type:system]
Optional description of the whole system.

## Major Module [type:system]
Description of this module.

### Feature Name [type:feature]
Detailed description.
- Bullet points become part of the description
- [Link Title](https://url.com)  ← extracted as a resource

```typescript
// Code blocks are extracted as codeSnippet of the feature
interface Example { id: string; }
```

### Another Feature [type:api]
Description

#### Deep Sub-feature [type:feature]
Can go as deep as needed.

Type values

system    — a major system or module (use for grouping features)
feature   — an individual feature or function
api       — an API endpoint or contract
ui        — a UI component, page, or screen
database  — a database schema, table, or model
security  — authentication, authorization, or security feature
devops    — infrastructure, CI/CD, or deployment
other     — anything else

5. Recommended Workflow

When a user gives you a system to add to DevIdeas, follow this order:

1. Check if the project already exists:
   GET /api/ai/ideas
   → look for a matching slug in the returned list

2. If exists, read the current tree to avoid duplicates:
   GET /api/ai/ideas?project={slug}

3. Create or append features:
   POST /api/ai/ideas
   {
     "projectSlug": "slug",
     "techStack": [...],        ← always include if known
     "markdown": "..."          ← full hierarchy
   }

   OR to append under an existing feature:
   POST /api/ai/ideas
   {
     "projectSlug": "slug",
     "parentId": "existing-feature-uuid",
     "markdown": "## Sub-system [type:system]\n..."
   }

4. Optionally update specific features with more detail:
   PUT /api/ai/ideas
   { "featureId": "uuid", "updates": { "description": "...", "codeSnippet": "..." } }

6. Data Schema

Project {
  id:           UUID
  slug:         string   — URL-friendly, e.g. "pharmacy-system"
  title:        string
  description:  string | null
  techStack:    string   — JSON array, e.g. '["Next.js","TypeScript"]'
  status:       "active" | "archived"
}

Feature {
  id:           UUID
  projectId:    UUID
  parentId:     string   — UUID of parent, or "" for root-level
  title:        string
  description:  string | null   — markdown supported
  type:         "system" | "feature" | "api" | "ui" | "database" | "security" | "devops" | "other"
  status:       "pending" | "in_progress" | "completed" | "archived"
  codeSnippet:  string | null
  resources:    [{ title: string, url: string }] | null
  notes:        string | null   — private, not shown on public page
  children:     Feature[]       — only in GET responses, not stored as a field
}

7. Full Example — Creating a New System

This is a complete example of adding a new project to DevIdeas in a single API call.

single POST call to create an entire system

curl -X POST https://ratanon.com/api/ai/ideas \
  -H "Authorization: Bearer devideas_a1fa233197d5a698da256a7b0e20c71f3816ad44f134a313d694aec0fd6835bf" \
  -H "Content-Type: application/json" \
  -d '{
    "projectSlug": "inventory-system",
    "techStack": ["Next.js 15", "TypeScript", "SQLite", "Drizzle ORM"],
    "markdown": "# Inventory Management System [type:system]\nระบบจัดการสินค้าคงคลังสำหรับธุรกิจขนาดกลาง\n\n## สินค้า [type:system]\nจัดการรายการสินค้าทั้งหมด\n\n### CRUD สินค้า [type:feature]\nเพิ่ม แก้ไข ลบ สินค้า พร้อมรูปภาพ\n\n### ค้นหาและกรอง [type:feature]\nค้นหาด้วยชื่อ, บาร์โค้ด, หมวดหมู่\n\n## สต็อก [type:system]\nติดตามสินค้าคงคลัง\n\n### รับสินค้า [type:feature]\nบันทึกการรับสินค้าจากซัพพลายเออร์\n\n### เบิกสินค้า [type:feature]\nบันทึกการเบิกสินค้าออก\n\n### แจ้งเตือนสต็อกต่ำ [type:feature]\nแจ้งเตือนเมื่อสินค้าต่ำกว่า minimum\n\n## รายงาน [type:system]\n\n### รายงานสต็อก [type:feature]\nมูลค่าสต็อก ยอดคงเหลือ\n\n### Dashboard [type:ui]\nกราฟภาพรวมสต็อกและการเคลื่อนไหว"
  }'

8. Error Responses

400 Bad Request    — missing required fields, or no features found in markdown
401 Unauthorized   — missing or invalid API key
403 Forbidden      — valid key but insufficient permissions (e.g. read-only key)
404 Not Found      — project or feature UUID not found
409 Conflict       — slug already exists (for project creation)
500 Server Error   — unexpected error

Error response format:
{ "success": false, "error": "Human-readable message" }

9. Notes

— Calling POST with an existing projectSlug APPENDS features (does not overwrite).
— To fully replace a project's features: delete the project first, then POST.
— projectSlug must match regex: /^[a-z0-9-]+$/ (lowercase, numbers, hyphens only).
— Markdown heading depth maps to tree depth. # = depth 0, ## = depth 1, etc.
— [type:xxx] tag must be at the END of the heading line.
— techStack is stored as a JSON array string, always pass as an array in the request.
— Public pages: /ideas  and  /ideas/{slug}  are accessible without auth.
— This page: https://ratanon.com/ideas/api-docs

https://ratanon.com/ideas/api-docs — ratanon devIdeas v1.0

Fetching data stream