I Need A Database

Reference

API reference

Reference for the HTTP API. Routes are organized around projects, collections, and documents.

Projects

GET/api/v1/projects
Lists projects owned by the signed-in account.
POST/api/v1/projects
Creates a project and returns its copy-once API key. Body: { "name": "My app" }.
GET/api/v1/projects/:projectId
Reads one project summary, including usage and collection counts.
DELETE/api/v1/projects/:projectId
Deletes one project and its collections, documents, and keys.

Collections

GET/api/v1/projects/:projectId/collections
Lists collections in one project.
POST/api/v1/projects/:projectId/collections
Creates a collection. Body: { "name": "recipes" }.
GET/api/v1/projects/:projectId/collections/:collection
Reads one collection summary, including document count and storage use.
DELETE/api/v1/projects/:projectId/collections/:collection
Deletes one collection and all documents inside it.

Documents

GET/api/v1/projects/:projectId/collections/:collection/documents
Lists documents, with optional filters, sort, limit, and cursor query parameters.
POST/api/v1/projects/:projectId/collections/:collection/documents
Creates a document from the JSON body.
GET/api/v1/projects/:projectId/collections/:collection/documents/:documentId
Reads one document by id.
PUT/api/v1/projects/:projectId/collections/:collection/documents/:documentId
Replaces one document body. Use If-Match with the current revision when overwrites must be guarded.
PATCH/api/v1/projects/:projectId/collections/:collection/documents/:documentId
Applies a JSON merge patch. Use If-Match with the current revision for optimistic concurrency.
DELETE/api/v1/projects/:projectId/collections/:collection/documents/:documentId
Deletes one document by id.

Document shape

Create and update requests store the JSON request body as the document data. Send your document fields directly. Do not wrap the body in a data key unless you want a data field inside your stored document.

create request
POST /api/v1/projects/proj_123/collections/recipes/documents
Content-Type: application/json

{
  "title": "Pasta",
  "servings": 4
}
response
{
  "id": "A1b2C3d4",
  "created_at": "2026-05-08T12:00:00Z",
  "updated_at": "2026-05-08T12:00:00Z",
  "revision": "rev_E5f6G7h8",
  "data": {
    "title": "Pasta",
    "servings": 4
  }
}

List response shape

List endpoints return an object with items and next_cursor. Do not treat a list response as a bare JSON array.

document list response
{
  "items": [
    {
      "id": "A1b2C3d4",
      "created_at": "2026-05-08T12:00:00Z",
      "updated_at": "2026-05-08T12:00:00Z",
      "revision": "rev_E5f6G7h8",
      "data": {
        "title": "Pasta",
        "servings": 4
      }
    }
  ],
  "next_cursor": null
}

Create project response

response
{
  "id": "recipe-app",
  "name": "Recipe App",
  "collectionCount": 0,
  "documentCount": 0,
  "apiKey": {
    "id": "key_...",
    "name": "Primary key",
    "token": "inadb_..."
  }
}

Browser and frontend calls

For frontend apps, create a small server-side route or serverless function. The frontend calls your route, and your route calls I Need A Database with the API key from environment variables.

Next.js or Vercel route handler
export async function GET() {
  const baseUrl = "https://ineedadatabase.com";
  const projectId = process.env.INEEDADATABASE_PROJECT_ID;
  const apiKey = process.env.INEEDADATABASE_API_KEY;

  const response = await fetch(
    `${baseUrl}/api/v1/projects/${projectId}/collections/recipes/documents`,
    {
      headers: {
        Authorization: `Bearer ${apiKey}`
      }
    }
  );

  return Response.json(await response.json(), { status: response.status });
}

Filtering and pagination

Filter, sort, limit, and cursor parameters are available on document list endpoints. Filters and sorting read fields from the JSON document body.

query examples
GET /api/v1/projects/proj_123/collections/recipes/documents?servings=4
GET /api/v1/projects/proj_123/collections/recipes/documents?servings_gt=2
GET /api/v1/projects/proj_123/collections/recipes/documents?title_contains=pasta
GET /api/v1/projects/proj_123/collections/orders/[email protected]
GET /api/v1/projects/proj_123/collections/recipes/documents?sort=created_at
GET /api/v1/projects/proj_123/collections/recipes/documents?sort=-created_at&limit=50
GET /api/v1/projects/proj_123/collections/recipes/documents?limit=50&cursor=abc123

Errors

error shape
{
  "error": {
    "code": "document_not_found",
    "message": "Document was not found."
  }
}