API documentation

Authentication

Send the API key in the Authorization header and a unique Idempotency-Key for every write request. Keys are for server-side use only.

Authorization: Bearer <YOUR_API_KEY>
Idempotency-Key: <CLIENT_GENERATED_UUID>
Content-Type: application/json

Do not send a user UUID. Each API key is already bound to its owner, and every request is authorized as that user. Idempotency-Key is a client-generated UUID that identifies one write attempt, not a user.

Endpoints

curl 'https://navs.site/api/v1/categories?locale=en'

{
  "code": 200,
  "msg": "Categories retrieved successfully.",
  "data": {
    "locale": "en",
    "categories": [
      {
        "slug": "ai-design-tools",
        "name": "AI Design Tools"
      }
    ]
  },
  "timestamp": 1723526400000
}

curl -X POST https://navs.site/api/v1/media/images \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -F "image=@./preview.png"

{
  "code": 201,
  "msg": "Image uploaded successfully.",
  "data": {
    "mediaUploadId": "media_xxx",
    "expiresAt": "2026-08-19T05:00:00.000Z"
  },
  "timestamp": 1723526400000
}

curl -X POST https://navs.site/api/v1/tools \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Idempotency-Key: <CLIENT_GENERATED_UUID>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Example Studio",
  "url": "https://example.com",
  "mediaUploadId": "<MEDIA_UPLOAD_ID>",
  "description": "A practical AI workspace for product teams and creative collaboration.",
  "detail": "Example Studio helps product teams create, revise, and share visual work with an AI-assisted workflow.",
  "categories": [
    "ai-design-tools"
  ],
  "tags": "design, collaboration",
  "logo": "https://example.com/logo.png",
  "videoUrl": "https://www.youtube.com/watch?v=example",
  "pricePlans": "Freemium",
  "supportEmail": "[email protected]",
  "faqUrl": "https://example.com/faq",
  "reason": "A useful tool for directory visitors."
}'

{
  "code": 201,
  "msg": "Tool submitted successfully.",
  "data": {
    "id": "example-com",
    "status": "pending"
  },
  "timestamp": 1723526400000
}

Response format

Every response uses code (the HTTP status), msg (a human-readable summary), data (business data or null), and timestamp (Unix milliseconds). Failed responses also include errorCode for programmatic handling. The exact data fields are listed under each endpoint.

{
  "code": 201,
  "msg": "Tool submitted successfully.",
  "data": {
    "id": "example-com",
    "status": "pending"
  },
  "timestamp": 1723526400000
}

Failure response

{
  "code": 422,
  "msg": "The request failed validation.",
  "data": null,
  "timestamp": 1723526400000,
  "errorCode": "VALIDATION_ERROR"
}

Idempotency and retries

Repeating the same key with the same validated request returns the original result without creating another submission or using credits again. A different request with the same key returns a replay-mismatch error.

REST conventions

The API uses HTTPS, resource-oriented paths, HTTP methods, and matching HTTP status codes. Requests and responses use JSON except POST /api/v1/media/images, which accepts multipart/form-data.

Common errors

401 UNAUTHORIZED

The API key is missing, invalid, revoked, or unavailable.

403 API_ACCESS_REQUIRED

The current membership does not include API access.

429 RATE_LIMITED

The key has reached its request limit. Retry after the response delay.

402 INSUFFICIENT_CREDITS

Neither the current membership credits nor purchased credits can cover the operation.

422 VALIDATION_ERROR

The request did not pass validation; no credits are used.

409 IDEMPOTENCY_KEY_REPLAY_MISMATCH

The idempotency key was previously used with a different validated request.