Repository Management API

Manage repositories through the Management API. Requires JWT authentication.

---

Create Repository

POST /api/v1/management/databases/{databaseId}/repositories

Creates a new repository in a database.

Request:

{
  "name": "companies",
  "entityName": "Company",
  "schema": {
    "name": { "type": "string", "required": true },
    "industry": { "type": "string", "required": false },
    "employeeCount": { "type": "number", "required": false }
  }
}

Field	Type	Required	Description
name	string	Yes	Repository name
entityName	string	Yes	Entity type name
schema	object	No	Schema definition for validation

Response (201 Created):

{
  "repositoryId": "repo_abc123",
  "databaseId": "db_abc123",
  "name": "companies",
  "entityName": "Company",
  "createdAt": "2024-01-15T10:00:00Z"
}

---

List Repositories

GET /api/v1/management/databases/{databaseId}/repositories

Lists all repositories in a database.

Response (200 OK):

{
  "repositories": [
    {
      "repositoryId": "repo_abc123",
      "databaseId": "db_abc123",
      "name": "companies",
      "entityName": "Company",
      "status": "Active",
      "schema": {
        "name": { "type": "string", "required": true }
      },
      "itemCount": 500,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "nextCursor": null
}

---

Get Repository

GET /api/v1/management/databases/{databaseId}/repositories/{repositoryId}

Gets a specific repository by ID.

Response (200 OK): Same as individual repository in list response.

---

Delete Repository

DELETE /api/v1/management/databases/{databaseId}/repositories/{repositoryId}

Deletes a repository and all its entities.

Warning

This permanently deletes the repository and all its data.

Response (204 No Content): Empty body on success.

---

Schema Definition

Define schemas for entity validation:

{
  "schema": {
    "name": {
      "type": "string",
      "required": true,
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "required": true,
      "pattern": "^[^@]+@[^@]+\\.[^@]+$"
    },
    "age": {
      "type": "number",
      "required": false,
      "min": 0,
      "max": 150
    },
    "isActive": {
      "type": "boolean",
      "required": false,
      "default": true
    },
    "tags": {
      "type": "array",
      "required": false,
      "items": { "type": "string" }
    }
  }
}

Schema Field Types

Type	Description	Validation Options
string	Text value	minLength, maxLength, pattern
number	Numeric value	min, max
boolean	True/false	-
array	List of values	items, minItems, maxItems
object	Nested object	properties

---

Code Examples

C# SDK

// Create repository
var createResult = await client.Repositories.CreateAsync(
    "db_abc123",
    new CreateRepositoryRequest(
        Name: "customers",
        EntityName: "Customer",
        Schema: new Dictionary<string, SchemaField>
        {
            ["name"] = new() { Type = "string", Required = true },
            ["email"] = new() { Type = "string", Required = true },
            ["tier"] = new() { Type = "string", Required = false }
        }
    )
);

// List repositories
var listResult = await client.Repositories.ListAsync("db_abc123");

foreach (var repo in listResult.Value.Repositories)
{
    Console.WriteLine($"{repo.Name} ({repo.EntityName}): {repo.ItemCount} items");
}

// Get repository
var repoResult = await client.Repositories.GetAsync("db_abc123", "repo_abc123");

// Delete repository
var deleteResult = await client.Repositories.DeleteAsync("db_abc123", "repo_abc123");

cURL

# Create repository
curl -X POST "https://api.terrascale.io/api/v1/management/databases/db_abc123/repositories" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customers",
    "entityName": "Customer",
    "schema": {
      "name": { "type": "string", "required": true },
      "email": { "type": "string", "required": true }
    }
  }'

# List repositories
curl "https://api.terrascale.io/api/v1/management/databases/db_abc123/repositories" \
  -H "Authorization: Bearer eyJhbGci..."

# Delete repository
curl -X DELETE "https://api.terrascale.io/api/v1/management/databases/db_abc123/repositories/repo_abc123" \
  -H "Authorization: Bearer eyJhbGci..."

---

Repository vs Raw Items

Feature	Repository	Raw Items
Schema validation	Yes	No
Auto-generated IDs	Yes	No
Timestamps	Automatic	Manual
Type safety (SDK)	Yes	No
Flexibility	Structured	Freeform

---

Next Steps

• Repository Operations - Use repository API
• Database Management - Manage databases
• Repository Guide - Repository pattern guide