/v1/apis.*

Migrate API namespace management endpoints from v1 to v2

This guide covers API namespace management endpoints for creating and managing API containers that organize your keys.

Overview

API endpoints manage the namespaces that contain your keys, providing CRUD operations for API management and key listing.

Key Changes in v2:

• Response format: Direct responses → {meta, data} envelope
• HTTP methods: Some GET → POST changes for consistency
• Enhanced responses: Request IDs for debugging and pagination metadata
• Consistent structure: All responses follow same envelope pattern

Migration Impact:

• Existing in v1: Full API CRUD operations and key listing functionality
• Enhanced in v2: Improved response format, better pagination, and enhanced filtering
• Maintained in v2: All core API management functionality with consistent request patterns

---

POST /v1/apis.createApi → POST /v2/apis.createApi

Key Changes:

• Response format: Direct response → {meta, data} envelope

Request Format

Create API Request

{
  "name": "Production API"
}

Response Changes

Create API Response Diff

// v1 Response (direct, no wrapper)
{
  "apiId": "api_1234567890abcdef"
}

// v2 Response (with meta envelope)
{
  "meta": { 
    "requestId": "req_createapi123"
  }, 
  "data": { 
    "apiId": "api_1234567890abcdef"
  } 
}

cURL Examples

API Endpoint & Domain Change

# v1: api.unkey.dev domain
curl -X POST https://api.unkey.dev/v1/apis.createApi
  -H "Authorization: Bearer <your-root-key>"
  -H "Content-Type: application/json"
  -d '{"name": "Production API"}'

# v2: api.unkey.com domain
curl -X POST https://api.unkey.com/v2/apis.createApi
  -H "Authorization: Bearer <your-root-key>"
  -H "Content-Type: application/json"
  -d '{"name": "Production API"}'

---

GET /v1/apis.getApi → POST /v2/apis.getApi

Key Changes:

• HTTP method: GET → POST
• Request body format required instead of query parameters
• Response format: Direct response → {meta, data} envelope

Method Change

HTTP Method & Parameter Change

# v1: GET with query parameters
curl -X GET "https://api.unkey.dev/v1/apis.getApi?apiId=api_123"
  -H "Authorization: Bearer <your-root-key>"

# v2: POST with request body
curl -X POST https://api.unkey.com/v2/apis.getApi
  -H "Authorization: Bearer <your-root-key>"
  -H "Content-Type: application/json"
  -d '{"apiId": "api_123"}'

Response Changes

Get API Response Diff

// v1 Response (direct, no wrapper)
{
  "id": "api_123", 
  "workspaceId": "ws_xyz789", 
  "name": "Production API"
}

// v2 Response (with meta envelope, no workspaceId)
{
  "meta": { 
    "requestId": "req_getapi456"
  }, 
  "data": { 
    "id": "api_123", 
    "name": "Production API"
  } 
}

Complete Examples

Complete Examples

# v1: GET with query parameters
curl -X GET "https://api.unkey.dev/v1/apis.getApi?apiId=api_123"
  -H "Authorization: Bearer <your-root-key>"

# v2: POST with request body
curl -X POST https://api.unkey.com/v2/apis.getApi
  -H "Authorization: Bearer <your-root-key>"
  -H "Content-Type: application/json"
  -d '{"apiId": "api_123"}'

---

GET /v1/apis.listKeys → POST /v2/apis.listKeys

Key Changes:

• HTTP method: GET → POST
• Request body format required instead of query parameters
• Enhanced filtering and pagination options
• Response format: Direct response → {meta, data} envelope

Request Changes

List Keys Request Diff

// v1: Query parameters only
// ?apiId=api_123&limit=100

// v2: Request body with enhanced options
{
  "apiId": "api_123",
  "limit": 100,
  "cursor": "optional_cursor_for_pagination", 
  "externalId": "optional_filter_by_external_id"
}

Response Changes

List Keys Response Diff

// v1 Response (direct structure with metadata)
{
  "keys": [ 
    { 
      "id": "key_123", 
      "name": "Production Key", 
      "start": "prod_1234"
    } 
  ], 
  "cursor": "next_page_cursor", 
  "total": 42
}

// v2 Response (meta envelope with direct key array)
{
  "meta": { 
    "requestId": "req_listkeys789"
  }, 
  "data": [ 
    { 
      "keyId": "key_123", 
      "name": "Production Key", 
      "start": "prod_1234", 
      "externalId": "customer_789", 
      "enabled": true
    } 
  ], 
  "pagination": { 
    "cursor": "next_page_cursor_here", 
    "hasMore": true
  } 
}

Filtering Examples

Enhanced Filtering Options

// Basic listing
{
  "apiId": "api_123",
  "limit": 50
}

// Filter by external ID
{
  "apiId": "api_123",
  "externalId": "customer_789", 
  "limit": 50
}

// Pagination
{
  "apiId": "api_123",
  "cursor": "cursor_from_previous_response", 
  "limit": 50
}

cURL Examples

Method & Parameter Changes

# v1: GET with query parameters
curl -X GET "https://api.unkey.dev/v1/apis.listKeys?apiId=api_123&limit=100"
  -H "Authorization: Bearer <your-root-key>"

# v2: POST with enhanced request body
curl -X POST https://api.unkey.com/v2/apis.listKeys
  -H "Authorization: Bearer <your-root-key>"
  -H "Content-Type: application/json"
  -d '{"apiId": "api_123", "limit": 100, "cursor": "optional_cursor", "externalId": "optional_filter"}'

---

POST /v1/apis.deleteApi → POST /v2/apis.deleteApi

Key Changes:

• Response format: Direct response → {meta, data} envelope

Request Format

Delete API Request

{
  "apiId": "api_123"
}

Response Changes

Delete API Response Diff

// v1 Response (empty object)
{} 

// v2 Response (meta envelope with empty data)
{
  "meta": { 
    "requestId": "req_deleteapi999"
  }, 
  "data": {} 
}

cURL Examples

Domain Change Only

# v1: api.unkey.dev domain
curl -X POST https://api.unkey.dev/v1/apis.deleteApi
  -H "Authorization: Bearer <your-root-key>"
  -H "Content-Type: application/json"
  -d '{"apiId": "api_123"}'

# v2: api.unkey.com domain
curl -X POST https://api.unkey.com/v2/apis.deleteApi
  -H "Authorization: Bearer <your-root-key>"
  -H "Content-Type: application/json"
  -d '{"apiId": "api_123"}'

---

POST /v1/apis.deleteKeys → Removed in v2

Purpose: Delete all keys within an API namespace.

Migration Path: Use individual POST /v2/keys.deleteKey calls for each key or delete the entire API with POST /v2/apis.deleteApi.

v1 Usage

v1: Delete all keys in API

curl -X POST https://api.unkey.dev/v1/apis.deleteKeys
  -H "Authorization: Bearer <your-root-key>"
  -H "Content-Type: application/json"
  -d '{"apiId": "api_123"}'

v2 Migration Options

Option 1: Delete Individual Keys

# First, list keys to get their IDs
curl -X POST https://api.unkey.com/v2/apis.listKeys
  -H "Authorization: Bearer <your-root-key>"
  -H "Content-Type: application/json"
  -d '{"apiId": "api_123"}'

# Then delete each key individually
curl -X POST https://api.unkey.com/v2/keys.deleteKey
  -H "Authorization: Bearer <your-root-key>"
  -H "Content-Type: application/json"
  -d '{"keyId": "key_123"}'

Option 2: Delete Entire API

curl -X POST https://api.unkey.com/v2/apis.deleteApi
  -H "Authorization: Bearer <your-root-key>"
  -H "Content-Type: application/json"
  -d '{"apiId": "api_123"}'

v2 Implementation

Programmatic Migration Example

// v2: Migration helper function
async function deleteAllKeysInApi(apiId: string) {
  // List all keys first
  const response = await fetch('/v2/apis.listKeys', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <root-key>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ apiId })
  });

  const { data } = await response.json();

  // Delete each key individually
  for (const key of data) {
    await fetch('/v2/keys.deleteKey', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer <root-key>',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ keyId: key.keyId })
    });
  }
}