REST API

API Documentation

Create and manage listings programmatically. Authenticate with API keys and upload code directly from your CI/CD pipeline or scripts.

Base URL:https://codecudos.com

Authentication

All authenticated endpoints require a Bearer token. Generate API keys from your profile page.

curl -H "Authorization: Bearer sk_your_api_key_here" \
  https://codecudos.com/api/v1/listings

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

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)
`500`	Internal server error

Ready to get started?

Generate an API key and start uploading listings programmatically.

Generate API Key