Every endpoint, in one place.

Authentication

Send your API key as a Bearer token on every request. Keys look like sk-<key id>-<secret>; mint them from your dashboard or with POST /keys. The four single-item GET endpoints addressed by id also accept a signed URL instead of a header.

$ curl https://api.taglydb.com/indexes \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

Requests and responses

• Base URL: https://api.taglydb.com. Request bodies are JSON (Content-Type: application/json), except blob uploads, which are multipart/form-data.
• Unknown body fields and unknown query parameters are rejected rather than ignored. For the optional key and tags fields, sending null means the same as leaving them out.
• Ids are UUIDs, except API key ids, which are 27-character alphanumeric strings. Timestamps are ISO 8601 in UTC.
• Every response carries an X-Request-Id header, and responses are marked Cache-Control: no-store (signed URLs are the one exception).

Keys and tags

• A key is 1–128 characters of letters, digits, ., _ and -, starting with a letter or digit. It must be unique in its scope — among your indexes, within one index, or among your standalone items — or the write fails with 409 conflict. Any number of resources can have no key.
• Tags are a flat object of string values: at most 16 entries, tag keys 1–64 characters, values up to 256 characters.

Pagination

List endpoints return { items, nextCursor }, oldest first. Pass limit (1–250, default 100) to size a page and cursor=<nextCursor> to fetch the next one; nextCursor is null on the last page. A cursor only works with the same filters it was issued for.

$ curl "https://api.taglydb.com/indexes/$IDX/items?limit=50" \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

{ "items": [ … ], "nextCursor": "eyJ2IjoxLCJhZnRlciI6…" }

$ curl "https://api.taglydb.com/indexes/$IDX/items?limit=50&cursor=eyJ2IjoxLCJhZnRlciI6…" \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

{ "items": [ … ], "nextCursor": null }

Filtering

Index and item listings accept a repeatable tag=<key>=<value> parameter (up to 16) and an exact-match key parameter. Repeating the same tag key ORs its values; different tag keys are ANDed.

# (team is billing OR support) AND priority is high
$ curl "https://api.taglydb.com/indexes/$IDX/items?tag=team=billing&tag=team=support&tag=priority=high" \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

The item object

Item endpoints return this metadata. It never includes the payload, except where noted.

{
  "id": "0199c4e3-5c10-7a4e-b2f7-4d81c09a6e3b",
  "key": "ticket-1042",
  "tags": { "team": "billing", "priority": "high" },
  "createdAt": "2026-09-23T09:14:02.911Z",
  "sizeBytes": 42,
  "storedBytes": 46,
  "encoding": "br",
  "contentType": "application/json"
}

The data field

Endpoints that put payloads into a JSON response — the /full endpoints and /items/data — return the item object plus a data field. For a JSON item it holds the stored value verbatim; for a blob it holds {"b64": "…"}, the bytes base64-encoded. The media type isn't repeated inside data; read it from contentType. Base64 only ever appears inside JSON responses: fetching a blob directly returns its real bytes.

// A JSON item: data is the stored value, verbatim
{ "id": "0199c4e3-5c10-7a4e-b2f7-4d81c09a6e3b", "contentType": "application/json", …,
  "data": { "subject": "Refund request", "amount": 42.5 } }

// A blob item: the same fields, with the bytes base64-encoded
{ "id": "0199c4e4-0d78-7361-9532-b5e435cf72c8", "contentType": "application/pdf", …,
  "data": { "b64": "JVBERi0xLjQgZmFrZSBwZGYgYnl0ZXM=" } }

Limits

• Whole request: 8 MiB, including any multipart framing.
• One item's stored payload (storedBytes): 1,900,000 bytes.
• One /items/data response: 16 MiB of matching stored payloads.
• Signed URLs: valid for at most 7 days (604,800 seconds).

Exceeding a size limit returns 413 (payload-too-large or bulk-payload-too-large). Storage across the whole account is capped by your plan — 100 MB on Free — and a write past it returns 413 storage-limit-exceeded.

An index is a collection of items, permanently either json or blob. Indexes can't be changed or deleted once created.

$ curl -X POST https://api.taglydb.com/indexes \
     -H "Authorization: Bearer $TAGLYDB_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "key": "support-tickets", "type": "json", "tags": { "env": "prod" } }'

{
  "id": "0199c4e3-01b2-7d9a-8c55-3f0e6a9b2d14",
  "key": "support-tickets",
  "tags": { "env": "prod" },
  "type": "json",
  "createdAt": "2026-09-23T09:13:20.004Z"
}

$ curl "https://api.taglydb.com/indexes?tag=env=prod" \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

{ "items": [ { "id": "0199c4e3-01b2-…", "key": "support-tickets", "tags": { "env": "prod" }, "type": "json", "createdAt": "…" } ],
  "nextCursor": null }

$ curl https://api.taglydb.com/indexes/by-key/support-tickets \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

$ curl https://api.taglydb.com/indexes/$IDX \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

Items stored in an index can be listed, filtered and fetched in bulk. An item's key is unique within its index. Items can't be changed or deleted once written.

$ curl -X POST https://api.taglydb.com/indexes/$IDX/items \
     -H "Authorization: Bearer $TAGLYDB_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "key": "ticket-1042", "tags": { "team": "billing", "priority": "high" },
           "data": { "subject": "Refund request", "amount": 42.5 } }'

# In a blob index: multipart, with the file's real media type on the data part
$ curl -X POST https://api.taglydb.com/indexes/$BLOB_IDX/items \
     -H "Authorization: Bearer $TAGLYDB_API_KEY" \
     -F "key=invoice-1042" \
     -F 'tags={"team":"billing"};type=application/json;filename=tags.json' \
     -F "data=@./invoice.pdf;type=application/pdf"

$ curl "https://api.taglydb.com/indexes/$IDX/items?tag=team=billing&limit=20" \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

{ "items": [ { "id": "0199c4e3-5c10-…", "key": "ticket-1042", "tags": { … }, "createdAt": "…",
               "sizeBytes": 42, "storedBytes": 46, "encoding": "br", "contentType": "application/json" } ],
  "nextCursor": null }

$ curl "https://api.taglydb.com/indexes/$IDX/items/data?tag=team=billing&tag=priority=high" \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

{
  "items": [
    {
      "id": "0199c4e3-5c10-7a4e-b2f7-4d81c09a6e3b",
      "key": "ticket-1042",
      "tags": { "team": "billing", "priority": "high" },
      "createdAt": "2026-09-23T09:14:02.911Z",
      "sizeBytes": 42,
      "storedBytes": 46,
      "encoding": "br",
      "contentType": "application/json",
      "data": { "subject": "Refund request", "amount": 42.5 }
    }
  ]
}

$ curl https://api.taglydb.com/indexes/$IDX/items/by-key/ticket-1042 \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

{"subject":"Refund request","amount":42.5}

# A blob comes back as its own bytes, with its own Content-Type
$ curl https://api.taglydb.com/indexes/$BLOB_IDX/items/$ITEM \
     -H "Authorization: Bearer $TAGLYDB_API_KEY" -o invoice.pdf

$ curl https://api.taglydb.com/indexes/$IDX/items/$ITEM/full \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

{ "id": "0199c4e3-5c10-…", "key": "ticket-1042", "tags": { … }, "createdAt": "…",
  "sizeBytes": 42, "storedBytes": 46, "encoding": "br", "contentType": "application/json",
  "data": { "subject": "Refund request", "amount": 42.5 } }

A standalone item belongs to no index. Its key is unique among your standalone items, so it can be fetched by key alone. Standalone items can't be listed or filtered, changed or deleted, and these routes only ever find standalone items — an item stored in an index returns 404 here.

# JSON: an application/json body
$ curl -X POST https://api.taglydb.com/items \
     -H "Authorization: Bearer $TAGLYDB_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "key": "latest-report", "tags": { "kind": "report" }, "data": { "ok": true } }'

# Blob: a multipart body
$ curl -X POST https://api.taglydb.com/items \
     -H "Authorization: Bearer $TAGLYDB_API_KEY" \
     -F "key=logo" \
     -F "data=@./logo.png;type=image/png"

$ curl https://api.taglydb.com/items/$ITEM \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

$ curl https://api.taglydb.com/items/$ITEM/full \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

$ curl https://api.taglydb.com/items/by-key/logo \
     -H "Authorization: Bearer $TAGLYDB_API_KEY" -o logo.png

$ curl https://api.taglydb.com/items/by-key/latest-report/full \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

A signed URL lets something without your API key fetch one item, by id, until the URL expires. It works for indexed and standalone items alike.

$ curl -X POST https://api.taglydb.com/items/$ITEM/sign \
     -H "Authorization: Bearer $TAGLYDB_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "view": "data", "expiresIn": 86400 }'

{
  "url": "https://api.taglydb.com/indexes/0199c4e4-…/items/0199c4e4-0d78-…?keyId=2c9j1Q7Kz4XU9wVhP3mTfAsLrBd&expires=1790241242&sig=q3Jx…",
  "expiresAt": "2026-09-24T09:14:02.000Z"
}

# Anyone with the URL can fetch the item, no Authorization header
$ curl -o invoice.pdf "https://api.taglydb.com/indexes/0199c4e4-…/items/0199c4e4-0d78-…?keyId=…&expires=…&sig=…"

Using a signed URL

• Fetch it with a plain GET and no Authorization header. If you do send one, it is used instead of the signature — and must be valid.
• Use the URL exactly as returned. Adding query parameters, changing the view, or using it after expiresAt returns 401 unauthorized.
• The URL stops working if the API key that minted it is revoked.
• Responses to a signed URL are cacheable: Cache-Control: public, with a max-age of the time left before expiry, capped at one hour.

Manage your own keys programmatically — useful for rotation. The dashboard does the same things with a UI. Your list also includes the key the dashboard uses on your behalf; revoking it through the API stops the dashboard from working.

$ curl -X POST https://api.taglydb.com/keys \
     -H "Authorization: Bearer $TAGLYDB_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "key": "nightly-etl" }'

{
  "id": "2c9j1Q7Kz4XU9wVhP3mTfAsLrBd",
  "key": "nightly-etl",
  "credential": "sk-2c9j1Q7Kz4XU9wVhP3mTfAsLrBd-9mLkP2xQ7VtYbR4nJhWaGsD8FcXe",
  "createdAt": "2026-09-23T09:20:11.310Z",
  "revokedAt": null
}

$ curl https://api.taglydb.com/keys \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

{ "items": [ { "id": "2c9j1Q7Kz4XU9wVhP3mTfAsLrBd", "key": "nightly-etl",
               "createdAt": "2026-09-23T09:20:11.310Z", "revokedAt": null } ],
  "nextCursor": null }

$ curl -X DELETE https://api.taglydb.com/keys/2c9j1Q7Kz4XU9wVhP3mTfAsLrBd \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

Credits your account has used. Usage is recorded shortly after each request, not in its own response. See Credits and usage for how it's measured.

$ curl https://api.taglydb.com/usage \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

{
  "plan": "free",
  "creditsUsed": 1.482,
  "creditLimit": 1000,
  "creditsRemaining": 998.518,
  "overage": false,
  "resetsAt": "2026-11-01T00:00:00.000Z",
  "storageBytes": 2500000,
  "storageLimit": 100000000,
  "byKey": [
    { "id": "2c9j1Q7Kz4XU9wVhP3mTfAsLrBd", "key": "nightly-etl", "creditsUsed": 1.482 }
  ]
}

$ curl "https://api.taglydb.com/usage/history?days=7" \
     -H "Authorization: Bearer $TAGLYDB_API_KEY"

{
  "keys": [ { "id": "2c9j1Q7Kz4XU9wVhP3mTfAsLrBd", "key": "nightly-etl" } ],
  "days": [
    { "apiKeyId": "2c9j1Q7Kz4XU9wVhP3mTfAsLrBd", "day": "2026-09-22",
      "creditsRead": 0.912, "creditsWrite": 0.31 },
    { "apiKeyId": "2c9j1Q7Kz4XU9wVhP3mTfAsLrBd", "day": "2026-09-23",
      "creditsRead": 0.2, "creditsWrite": 0.06 }
  ]
}

Every error uses one shape, RFC 9457 “Problem Details for HTTP APIs”: a flat JSON object with Content-Type: application/problem+json. Branch on type, which is stable; title is a fixed label for the type and detail explains this particular failure. Include requestId (also sent as the X-Request-Id header) if you contact support.

HTTP/1.1 404 Not Found
Content-Type: application/problem+json
X-Request-Id: 0199c400-9d21-4c1e-8f0a-6b2d7e1c9a55

{
  "type": "https://api.taglydb.com/errors/item-not-found",
  "title": "Item not found",
  "status": 404,
  "detail": "Item not found",
  "requestId": "0199c400-9d21-4c1e-8f0a-6b2d7e1c9a55"
}

Error types

Each type is https://api.taglydb.com/errors/ followed by one of these.

validation-failed400 / 422

A value is invalid. 422 for a JSON request body (or a blob upload's tags); 400 for a query parameter, path segment or other upload part. detail names the field.

malformed-request400

The body isn't valid JSON, or a multipart upload is malformed or has missing, repeated or unknown parts.

invalid-id400

An index or item id in the path isn't a well-formed id at all.

invalid-key-id400

An API key id in the path isn't a well-formed key id.

invalid-cursor400

The cursor parameter isn't a cursor this API issued.

cursor-scope-mismatch400

The cursor was issued for a different listing or different filters. Re-list with the same tag/key filters.

unauthorized401

Missing, malformed, revoked or unknown API key — or a signed URL that is expired, tampered with or has extra query parameters.

credits-exhausted402

Your plan's credits are used up. Every request but GET /usage is refused until Free's monthly reset, or until more credits are added.

index-not-found404

No such index in your account.

item-not-found404

No such item at this address in your account (remember indexed and standalone items have separate routes).

key-not-found404

No such API key in your account.

route-not-found404

No endpoint matches this method and path.

conflict409

The key (or API-key label) you chose is already taken in that scope.

payload-too-large413

The request exceeds 8 MiB, or the item's stored payload exceeds 1,900,000 bytes.

storage-limit-exceeded413

This write would take your account past its plan's storage limit (100 MB on Free).

bulk-payload-too-large413

An items/data query matches more than 16 MiB of stored payloads. Narrow the filters.

unsupported-media-type415

Wrong Content-Type for this endpoint or index type, or a blob upload's tags part isn't application/json.

internal-error500

Something went wrong on our side. Quote the requestId if you contact support.

A 404 never tells you whether something exists in another account: anything that isn't yours is simply not found.