REST API

API Documentation

Create listings with API keys, or browse published catalog data without auth. ZIP and GitHub repo URLs are never returned — buyers get those after purchase.

Base URL:https://codecudos.com

Authentication

Write endpoints (create listing, API-key management) require a Bearer token. Generate API keys from your profile page. Catalog GET /api/v1/listings is public.

curl -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -X POST https://codecudos.com/api/v1/listings \
  -d '{"title":"My kit","description":"Production-ready starter.","price":29.99,"category":"component"}'

Security: API keys are shown once at creation. Store them securely. Keys are hashed server-side — we cannot recover lost keys.

List Listings

GET/api/v1/listings

Published catalog only. No API key required. ZIP and repo URLs are omitted; use hasZip / hasRepo. Rate limited to 60 requests per minute per IP.

Query parameters

Field	Type	Notes
`page`	number	Default 1
`limit`	number	Default 20, max 100
`category`	string	Category slug
`sellerId`	string	Filter by seller

Example

curl "https://codecudos.com/api/v1/listings?category=component&limit=5"

Response (200)

{
  "listings": [
    {
      "id": "clx123...",
      "slug": "react-dashboard-kit",
      "title": "React Dashboard Kit",
      "price": 29.99,
      "isVibeCoded": false,
      "hasZip": true,
      "hasRepo": true,
      "demoUrl": "https://demo.example",
      "path": "/listings/component/react-dashboard-kit",
      "category": { "id": "...", "name": "Component", "slug": "component" },
      "images": [{ "url": "https://example.com/screenshot.png", "order": 0 }],
      "techStacks": [{ "id": "...", "name": "React", "slug": "react" }],
      "seller": { "id": "...", "name": "Ada", "image": null },
      "qualityGrade": "A",
      "qualityScore": 92,
      "avgRating": 4.5,
      "reviewCount": 12,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-02T00:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 5, "total": 1, "totalPages": 1 }
}

Get Listing

GET/api/v1/listings/:id

One published listing by id or slug. Includes description. Same privacy rules as the list endpoint.

Example

curl https://codecudos.com/api/v1/listings/react-dashboard-kit

Response (200)

{
  "id": "clx123...",
  "slug": "react-dashboard-kit",
  "title": "React Dashboard Kit",
  "description": "Admin dashboard with charts, tables, and dark mode.",
  "price": 29.99,
  "hasZip": true,
  "hasRepo": true,
  "path": "/listings/component/react-dashboard-kit"
}

Create Listing

POST/api/v1/listingsAuth required

Create a new listing. Requires SELLER role.

Request body

{
  "title": "Next.js SaaS Boilerplate",
  "description": "Production-ready starter with auth, payments, and dashboards.",
  "price": 49.99,
  "category": "full-app",
  "techStacks": ["nextjs", "react", "typescript", "stripe"],
  "images": ["https://example.com/screenshot.png"],
  "zipFileUrl": "https://example.com/source.zip",
  "isVibeCoded": true,
  "status": "DRAFT"
}

Parameters

Field	Type	Required	Description
`title`	string	Yes	3–100 characters
`description`	string	Yes	10–5000 chars, supports Markdown
`price`	number	Yes	Positive, max 2 decimals (USD)
`category`	string	Yes*	Category slug (or use `categoryId`)
`techStacks`	string[]	No	Tech stack slugs (or use `techStackIds`)
`images`	string[]	No	Up to 5 image URLs
`zipFileUrl`	string	No	URL to source code ZIP
`isVibeCoded`	boolean	No	Mark as AI/vibe coded (default: false)
`status`	string	No	`DRAFT` or `PUBLISHED` (default: DRAFT)

Example

curl -X POST https://codecudos.com/api/v1/listings \
  -H "Authorization: Bearer sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "React Dashboard Kit",
    "description": "Admin dashboard with charts, tables, and dark mode.",
    "price": 29.99,
    "category": "component",
    "techStacks": ["react", "tailwind-css", "typescript"],
    "isVibeCoded": false,
    "status": "DRAFT"
  }'

Response (201)

{
  "id": "clx123...",
  "title": "React Dashboard Kit",
  "price": 29.99,
  "status": "DRAFT",
  "isVibeCoded": false,
  "category": { "id": "...", "name": "Component", "slug": "component" },
  "techStacks": [
    { "id": "...", "name": "React", "slug": "react" },
    { "id": "...", "name": "Tailwind CSS", "slug": "tailwind-css" }
  ],
  "seller": { "id": "...", "name": "Your Name" },
  "createdAt": "2024-01-01T00:00:00.000Z"
}

List Categories

GET/api/categories

Fetch all available categories. Public endpoint, no auth needed.

Response (200)

[
  { "id": "...", "name": "Boilerplate", "slug": "boilerplate", "_count": { "listings": 5 } },
  { "id": "...", "name": "Component", "slug": "component", "_count": { "listings": 12 } },
  { "id": "...", "name": "Full App", "slug": "full-app", "_count": { "listings": 3 } },
  { "id": "...", "name": "Script", "slug": "script", "_count": { "listings": 8 } },
  { "id": "...", "name": "Template", "slug": "template", "_count": { "listings": 7 } },
  { "id": "...", "name": "Utility", "slug": "utility", "_count": { "listings": 4 } }
]

List Tech Stacks

GET/api/tech-stacks

Fetch all available tech stacks. Public endpoint, no auth needed.

Response (200)

[
  { "id": "...", "name": "React", "slug": "react" },
  { "id": "...", "name": "Next.js", "slug": "nextjs" },
  { "id": "...", "name": "TypeScript", "slug": "typescript" },
  { "id": "...", "name": "Tailwind CSS", "slug": "tailwind-css" },
  ...
]

API Key Management

Manage your API keys programmatically. These endpoints use session auth (cookies), not API key auth. For the easiest experience, use the profile page UI instead.

GET/api/api-keysAuth required

List all your API keys. Returns metadata only — keys are never shown after creation.

[
  {
    "id": "clx456...",
    "name": "CI Pipeline",
    "prefix": "sk_6922dd28",
    "lastUsedAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

POST/api/api-keysAuth required

Create a new API key. The full key is returned only once in the response — store it securely.

Request body

{ "name": "CI Pipeline" }

Response (201)

{
  "key": "sk_6922dd289ad2200acc6431a131c74b2d...",
  "prefix": "sk_6922dd28",
  "name": "CI Pipeline"
}

DELETE/api/api-keys/:idAuth required

Revoke an API key. This is immediate and irreversible.

curl -X DELETE https://codecudos.com/api/api-keys/clx456...

Error Handling

All errors return a consistent JSON shape:

{
  "error": "Human-readable error message",
  "details": [...]  // Optional: Zod validation details
}

Status	Meaning
`400`	Invalid request body or parameters
`401`	Missing or invalid API key
`403`	Insufficient permissions (SELLER role required)
`404`	Listing not found or unpublished
`429`	Rate limited — retry after the header value
`500`	Internal server error

Ready to get started?

Generate an API key and start uploading listings programmatically.

Generate API Key