# Access APIs

The Access APIs provide comprehensive data retrieval capabilities for the DeDi.global platform. These read-oriented endpoints allow you to look up, query, and explore namespaces, registries, and records with filtering and version management support.

🌐 **Public Read Access**: Lookup, query, version, and search endpoints are available without mandatory authentication. You may still send an API key when your integration standardizes authenticated requests.

## Overview

Access APIs are organized into three main categories:

* **Lookup APIs** - Retrieve detailed information about specific resources
* **Query APIs** - Search and filter collections of resources with pagination
* **Version APIs** - Manage and retrieve historical versions of resources

These access APIs support both current and historical data queries.

## Lookup APIs

Lookup APIs provide detailed information about specific resources using their identifiers.

### Namespace Lookup

Retrieve detailed information about a specific namespace.

**Endpoint:** `GET /dedi/lookup/{namespace}`

**Parameters:**

* `namespace` (path, required): Namespace ID or verified domain
* `version_id` (query, optional): Specific version to retrieve
* `as_on` (query, optional): Historical lookup date (YYYY-MM-DD format)

**Example Request:**

```typescript
const response = await fetch('https://api.dedi.global/dedi/lookup/my-namespace', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
```

**Success Response (200):**

```typescript
{
  "message": "Namespace details retrieved successfully",
  "data": {
    "domain": "example.com",
    "name": "my-namespace",
    "namespace_id": "did:cord:3yVazTQMc...",
    "digest": "0x123abc...",
    "description": "Production namespace for example.com services",
    "created_by": "did:cord:3xMxFkzY...",
    "genesis": "0x456def...",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "version": "0x789ghi...",
    "version_count": 3,
    "is_verified": true,
    "meta": {
      "category": "production",
      "region": "global"
    },
    "registry_count": 15,
    "ttl": 86400,
    "proof": {
      "type": "DediNamespaceProof2026",
      "namespace_did": "did:cord:3yVazTQMc...",
      "creator_did": "did:cord:3xMxFkzY...",
      "digest": "0x123abc...",
      "network_genesis": "0x101112..."
    }
  }
}
```

**Error Responses:**

* `400` - Invalid namespace parameter or date format
* `404` - Namespace not found or version not found
* `500` - Internal server error

### Registry Lookup

Retrieve detailed information about a specific registry.

**Endpoint:** `GET /dedi/lookup/{namespace}/{registry_name}`

**Parameters:**

* `namespace` (path, required): Namespace ID or domain
* `registry_name` (path, required): Registry name
* `version_id` (query, optional): Specific version to retrieve
* `as_on` (query, optional): Historical lookup date (YYYY-MM-DD format)

**Example Request:**

```typescript
const response = await fetch('https://api.dedi.global/dedi/lookup/my-namespace/user-registry', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
```

**Success Response (200):**

```typescript
{
  "message": "Resource retrieved successfully",
  "data": {
    "namespace": "my-namespace",
    "namespace_id": "did:cord:3yVazTQMc...",
    "registry_id": "did:cord:3zAbcDef...",
    "registry_name": "user-registry",
    "digest": "0x456abc...",
    "description": "User management registry for authentication",
    "created_by": "did:cord:3xMxFkzY...",
    "tag": "membership",
    "schema": {
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "role": { "type": "string", "enum": ["admin", "user"] },
        "active": { "type": "boolean" }
      },
      "required": ["email", "role"]
    },
    "genesis": "0x789def...",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "state": "live",
    "meta": {
      "department": "engineering",
      "priority": "high"
    },
    "record_count": 150,
    "version_count": 2,
    "version": "0x012ghi...",
    "query_allowed": true,
    "ttl": 3600,
    "proof": {
      "type": "DediRegistryProof2026",
      "namespace_did": "did:cord:3yVazTQMc...",
      "registry_identifier": "did:cord:3zAbcDef...",
      "creator_did": "did:cord:3xMxFkzY...",
      "digest": "0x456abc...",
      "network_genesis": "0x101112..."
    }
  }
}
```

> **Important**: A `200` response indicates successful data retrieval, not that the registry is active. Always check the `state` field to verify the registry's current status before using it.

**Error Responses:**

* `400` - Missing namespace or registry name
* `404` - Namespace or registry not found
* `500` - Internal server error

### Record Lookup

Retrieve detailed information about a specific record.

**Endpoint:** `GET /dedi/lookup/{namespace}/{registry_name}/{record_name}`

**Parameters:**

* `namespace` (path, required): Namespace ID or domain
* `registry_name` (path, required): Registry name
* `record_name` (path, required): Record name
* `version_id` (query, optional): Specific version to retrieve
* `as_on` (query, optional): Historical lookup date (YYYY-MM-DD format)

**Example Request:**

```typescript
const response = await fetch('https://api.dedi.global/dedi/lookup/my-namespace/user-registry/john-doe', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
```

**Success Response (200):**

```typescript
{
  "message": "Resource retrieved successfully",
  "data": {
    "namespace": "my-namespace",
    "namespace_id": "did:cord:3yVazTQMc...",
    "registry_id": "did:cord:3zAbcDef...",
    "registry_name": "user-registry",
    "registry_state": "live",
    "record_id": "did:cord:3aRecDef...",
    "record_name": "john-doe",
    "description": "User record for John Doe",
    "digest": "0x789abc...",
    "schema": {
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "role": { "type": "string", "enum": ["admin", "user"] }
      }
    },
    "version_count": 3,
    "version": "0x345ghi...",
    "details": {
      "email": "john.doe@example.com",
      "role": "admin",
      "active": true,
      "last_login": "2024-01-01T10:30:00Z"
    },
    "meta": {
      "department": "engineering",
      "access_level": "high"
    },
    "genesis": "2024-01-01T00:00:00.000Z",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "created_by": "did:cord:3xMxFkzY...",
    "state": "live",
    "ttl": 86400,
    "proof": {
      "type": "DediRecordProof2026",
      "namespace_did": "did:cord:3yVazTQMc...",
      "registry_identifier": "did:cord:3zAbcDef...",
      "record_identifier": "did:cord:3aRecDef...",
      "creator_did": "did:cord:3xMxFkzY...",
      "digest": "0x789abc...",
      "network_genesis": "0x101112..."
    }
  }
}
```

**Error Responses:**

* `400` - Missing required parameters
* `404` - Namespace, registry, or record not found
* `500` - Internal server error

## Query APIs

Query APIs enable searching and filtering collections with pagination support.

### Query Registries by Namespace

List all registries within a namespace with filtering options.

**Endpoint:** `GET /dedi/query/{namespace}`

**Parameters:**

* `namespace` (path, required): Namespace ID or domain
* `from` (query, optional): Filter from date (YYYY-MM-DD)
* `to` (query, optional): Filter to date (YYYY-MM-DD)
* `status` (query, optional): Filter by status (`active`, `inactive`)
* `name` (query, optional): Search by registry name (minimum 3 characters)
* `sort` (query, optional): Sort by `date`, `status`, `name`, or `id`
* `page` (query, optional): Page number for pagination
* `page_size` (query, optional): Items per page
* `as_on` (query, optional): Historical query date (YYYY-MM-DD)

**Example Request:**

```typescript
const response = await fetch('https://api.dedi.global/dedi/query/my-namespace?sort=date&page=1&page_size=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
```

**Success Response (200):**

```typescript
{
  "message": "Resource retrieved successfully",
  "data": {
    "namespace_id": "did:cord:3yVazTQMc...",
    "namespace_name": "my-namespace",
    "domain": "my-namespace.dedi.global",
    "created_by": "did:cord:3xMxFkzY...",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "total_registries": 25,
    "page_number": 1,
    "page_size": 10,
    "registries": [
      {
        "registry_id": "did:cord:3zAbcDef...",
        "registry_name": "user-registry",
        "description": "Registry for user profiles",
        "digest": "0x456def...",
        "tag": "users",
        "schema": {
          "type": "object",
          "properties": {
            "email": { "type": "string", "format": "email" }
          }
        },
        "genesis": "2024-01-01T00:00:00.000Z",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z",
        "created_by": "did:cord:3xMxFkzY...",
        "state": "live",
        "meta": {
          "category": "identity",
          "version": "v1.0"
        },
        "record_count": 150,
        "version_count": 3,
        "version": "0x789abc...",
        "query_allowed": true,
        "ttl": 86400
      }
    ]
  }
}
```

**Error Responses:**

* `404` - Namespace not found
* `500` - Internal server error

### Query Records by Registry

List all records within a registry with filtering options.

**Endpoint:** `GET /dedi/query/{namespace}/{registry_name}`

**Parameters:**

* `namespace` (path, required): Namespace ID or domain
* `registry_name` (path, required): Registry name
* `from` (query, optional): Filter from date (YYYY-MM-DD)
* `to` (query, optional): Filter to date (YYYY-MM-DD)
* `state` (query, optional): Filter by state (`live`)
* `name` (query, optional): Search by record name (minimum 3 characters)
* `sort` (query, optional): Sort by `date`, `status`, `name`, or `id`
* `page` (query, optional): Page number for pagination
* `page_size` (query, optional): Items per page
* `as_on` (query, optional): Historical query date (YYYY-MM-DD)

**Example Request:**

```typescript
const response = await fetch('https://api.dedi.global/dedi/query/my-namespace/user-registry?state=live&sort=name', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
```

**Success Response (200):**

```typescript
{
  "message": "Resource retrieved successfully",
  "data": {
    "namespace_id": "did:cord:3yVazTQMc...",
    "namespace_name": "my-namespace",
    "registry_name": "user-registry",
    "registry_id": "did:cord:3zAbcDef...",
    "schema": {
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "role": { "type": "string", "enum": ["admin", "user"] }
      }
    },
    "meta": {
      "category": "identity",
      "access_level": "public"
    },
    "created_by": "did:cord:3xMxFkzY...",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "total_records": 150,
    "total_pages": 15,
    "page_number": 1,
    "page_size": 10,
    "records": [
      {
        "record_id": "did:cord:3aRecDef...",
        "record_name": "john-doe",
        "description": "User record for John Doe",
        "digest": "0x789abc...",
        "details": {
          "email": "john.doe@example.com",
          "role": "admin",
          "active": true
        },
        "genesis": "2024-01-01T00:00:00.000Z",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z",
        "created_by": "did:cord:3xMxFkzY...",
        "state": "live",
        "version_count": 2,
        "version": "0x345ghi...",
        "ttl": 86400,
        "meta": {
          "department": "engineering",
          "access_level": "high"
        }
      }
    ]
  }
}
```

**Error Responses:**

* `404` - Registry or namespace not found
* `500` - Internal server error

### Query Registries by Schema Tag

Find verified registries by their schema tag across the platform.

**Endpoint:** `GET /dedi/{tag}/get-registry-by-tag`

**Parameters:**

* `tag` (path, required): Schema tag to filter by (e.g., `membership`, `public_key`, `revoke`)

> **Note:** The tag cannot be `custom` as this endpoint is specifically for standardized schemas.

**Authentication:** Not required

**Example Request:**

```typescript
const response = await fetch('https://api.dedi.global/dedi/membership/get-registry-by-tag', {
  method: 'GET'
});

const data = await response.json();
```

**Success Response (200):**

```typescript
{
  "message": "Resource retrieved successfully",
  "data": {
    "tag": "membership",
    "total_registries": 1,
    "registries": [
      {
        "registry_id": "did:cord:3zAbcDef...",
        "registry_name": "employee-registry",
        "namespace_id": "did:cord:3yVazTQMc...",
        "description": "Employee membership registry",
        "digest": "0x456def...",
        "tag": "membership",
        "schema": {
          "type": "object",
          "properties": {
            "email": { "type": "string", "format": "email" },
            "role": { "type": "string" },
            "department": { "type": "string" }
          }
        },
        "genesis": "2024-01-01T00:00:00.000Z",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z",
        "created_by": "did:cord:3xMxFkzY...",
        "state": "live",
        "meta": {
          "category": "membership",
          "version": "v2.0"
        },
        "record_count": 50,
        "version_count": 3,
        "version": "0x789abc...",
        "query_allowed": true,
        "ttl": 86400
      }
    ]
  }
}
```

**Error Responses:**

* `400` - Invalid tag (cannot be 'custom' or missing)
* `500` - Internal server error

## Version APIs

Version APIs provide access to historical versions and evolution tracking for all resources.

### Namespace Versions

Retrieve all available versions for a namespace.

**Endpoint:** `GET /dedi/versions/{namespace}`

**Parameters:**

* `namespace` (path, required): Namespace ID or domain

**Example Request:**

```typescript
const response = await fetch('https://api.dedi.global/dedi/versions/my-namespace', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
```

**Success Response (200):**

```typescript
{
  "message": "Resource retrieved successfully",
  "data": {
    "created_by": "did:cord:3xMxFkzY...",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "total_versions": 5,
    "versions": [
      "0x789ghi...", // Latest
      "0x456def...",
      "0x123abc...", // Oldest
    ],
    "ttl": 86400
  }
}
```

### Registry Versions

Retrieve all available versions for a registry.

**Endpoint:** `GET /dedi/versions/{namespace}/{registry_name}`

**Parameters:**

* `namespace` (path, required): Namespace ID or domain
* `registry_name` (path, required): Registry name

**Example Request:**

```typescript
const response = await fetch('https://api.dedi.global/dedi/versions/my-namespace/user-registry', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
```

**Success Response (200):**

```typescript
{
  "message": "Resource retrieved successfully",
  "data": {
    "registry_name": "user-registry",
    "created_by": "did:cord:3xMxFkzY...",
    "schema": {
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "role": { "type": "string" }
      }
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "total_versions": 3,
    "versions": [
      "0x345ghi...", // Latest
      "0x012def...",
      "0x789abc..."  // Oldest
    ],
    "ttl": 3600
  }
}
```

### Record Versions

Retrieve all available versions for a record.

**Endpoint:** `GET /dedi/versions/{namespace}/{registry_name}/{record_name}`

**Parameters:**

* `namespace` (path, required): Namespace ID or domain
* `registry_name` (path, required): Registry name
* `record_name` (path, required): Record name

**Example Request:**

```typescript
const response = await fetch('https://api.dedi.global/dedi/versions/my-namespace/user-registry/john-doe', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
```

**Success Response (200):**

```typescript
{
  "message": "Resource retrieved successfully",
  "data": {
    "created_by": "did:cord:3xMxFkzY...",
    "schema": {
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "role": { "type": "string" }
      }
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "total_versions": 4,
    "versions": [
      "0x567jkl...", // Latest
      "0x345ghi...",
      "0x123def...",
      "0x901abc..."  // Oldest
    ],
    "ttl": 86400
  }
}
```

## Error Handling

All Access APIs follow consistent error response patterns:

### Common Error Responses

**400 Bad Request:**

```typescript
{
  "message": "Invalid input: namespace is missing or empty"
}
```

**401 Unauthorized:**

```typescript
{
  "message": "Unauthorized: Invalid or missing authentication token"
}
```

**404 Not Found:**

```typescript
{
  "message": "Namespace not found"
}
```

**500 Internal Server Error:**

```typescript
{
  "message": "An unexpected error occurred"
}
```

## Best Practices

### Performance Optimization

1. **Use specific lookups** when you know exact resource identifiers
2. **Implement pagination** for large result sets
3. **Cache frequently accessed** namespace and registry data
4. **Use historical queries sparingly** as they are more resource-intensive

### Query Efficiency

1. **Apply filters** to reduce result set size
2. **Use date ranges** for time-based queries
3. **Sort consistently** to improve cache performance
4. **Implement client-side caching** for static data

### Version Management

1. **Track version counts** to detect updates
2. **Use version\_id** for reproducible results
3. **Cache version lists** as they change infrequently
4. **Implement version-aware** client logic

## Examples and Use Cases

### Real-time Data Synchronization

```typescript
// Check for updates and sync data
async function syncNamespaceData(namespaceId: string) {
  const current = await lookup.namespace(namespaceId);
  const cached = getCachedVersion(namespaceId);
  
  if (current.version_count > cached.version_count) {
    // Fetch and cache updated data
    await updateCache(namespaceId, current);
    
    // Sync registries if needed
    const registries = await query.registriesByNamespace(namespaceId);
    await syncRegistries(registries.data.registries);
  }
}
```

### Advanced Search Implementation

```typescript
// Multi-criteria registry search
async function searchRegistries(criteria: SearchCriteria) {
  const results = await query.registriesByNamespace(criteria.namespace, {
    from: criteria.dateRange.start,
    to: criteria.dateRange.end,
    name: criteria.searchTerm,
    sort: 'date',
    page: criteria.page,
    page_size: 20
  });
  
  // Filter by tag if specified
  if (criteria.schemaTag) {
    const taggedRegistries = await query.registriesByTag(criteria.schemaTag);
    return filterAndMerge(results.data, taggedRegistries.data);
  }
  
  return results.data;
}
```

### Historical Analysis

```typescript
// Analyze resource evolution over time
async function analyzeResourceHistory(namespace: string, registry: string) {
  const versions = await version.registry(namespace, registry);
  const analysis = {
    totalVersions: versions.data.total_versions,
    evolutionTimeline: [],
    schemaChanges: []
  };
  
  // Fetch each version for comparison
  for (const versionId of versions.data.versions) {
    const versionData = await lookup.registry(namespace, registry, { version_id: versionId });
    analysis.evolutionTimeline.push({
      version: versionId,
      timestamp: versionData.data.updated_at,
      changes: compareSchemas(versionData.data.schema)
    });
  }
  
  return analysis;
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dedi-global.gitbook.io/docs/dedi.global-developers/standard-apis/access.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.