Metadata API

Retrieve application metadata, database statistics, and API keys

The Metadata API provides administrative endpoints to monitor your InsForge backend, retrieve database statistics for dashboards, and manage API keys. These endpoints require admin authentication.

Get App Metadata

Retrieve comprehensive metadata about your InsForge application including version, environment, database configuration, and uptime.

Authentication

Requires either:

• Bearer Token: Admin JWT token in Authorization: Bearer <token> header
• API Key: API key in X-API-Key: <key> header

Response

name · string

Application name

version · string

Current version of the InsForge backend

environment · string

Deployment environment (e.g., production, staging)

database · object

Database connection information

database.host · string

Database server hostname

database.port · integer

Database server port

database.database · string

Database name

database.ssl · boolean

Whether SSL is enabled for database connections

uptime · number

Application uptime in seconds

timestamp · string

Current server timestamp in ISO 8601 format

Example Request

curl -X GET https://your-app.region.insforge.app/api/metadata \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Example Response

{
  "name": "Insforge Backend",
  "version": "2.0.0",
  "environment": "production",
  "database": {
    "host": "db.example.com",
    "port": 5432,
    "database": "insforge",
    "ssl": true
  },
  "uptime": 86400,
  "timestamp": "2024-01-21T10:30:00Z"
}

---

Get Database Metadata

Retrieve detailed database statistics including table information, record counts, and database size. Ideal for building admin dashboards.

Authentication

Requires either:

• Bearer Token: Admin JWT token in Authorization: Bearer <token> header
• API Key: API key in X-API-Key: <key> header

Response

tables · array

Array of table metadata objects

tables[].name · string

Table name

tables[].recordCount · integer

Number of records in the table

totalTables · integer

Total number of tables in the database

totalRecords · integer

Total number of records across all tables

databaseSize · string

Total database size (human-readable format)

lastUpdated · string

Timestamp when statistics were last updated

Example Request

curl -X GET https://your-app.region.insforge.app/api/metadata/database \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Example Response

{
  "tables": [
    {
      "name": "posts",
      "recordCount": 5678
    },
    {
      "name": "comments",
      "recordCount": 9012
    }
  ],
  "totalTables": 15,
  "totalRecords": 16924,
  "databaseSize": "125 MB",
  "lastUpdated": "2024-01-21T10:30:00Z"
}

Error Responses

error · string

Error code: UNAUTHORIZED

message · string

Human-readable error message

statusCode · integer

HTTP status code: 401

nextAction · string

Suggested action to resolve the error

---

Get API Key

Retrieve the API key for your InsForge backend. This is an admin-only endpoint that requires bearer token authentication (API key authentication is not allowed for this endpoint).

Authentication

Requires:

• Bearer Token: Admin JWT token in Authorization: Bearer <token> header

This endpoint only accepts bearer token authentication. You cannot use an API key to retrieve the API key.

Response

apiKey · string

The API key for your InsForge backend (format: ins_ followed by 32 hexadecimal characters)

Example Request

curl -X GET https://your-app.region.insforge.app/api/metadata/api-key \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

Example Response

{
  "apiKey": "ins_1234567890abcdef1234567890abcdef"
}

Error Responses

403 Forbidden - When a non-admin user attempts to access the endpoint:

{
  "error": "INSUFFICIENT_PERMISSIONS",
  "message": "Only admin users can access API keys",
  "statusCode": 403,
  "nextAction": "Contact an administrator for API key access"
}

---

When to Use Metadata APIs

Use these endpoints to:

• Monitor backend health: Check version, uptime, and environment configuration
• Build admin dashboards: Display database statistics and table information
• Retrieve API credentials: Get the API key for SDK configuration
• Debug connection issues: Verify database configuration and connectivity

Common Use Cases

1. Admin Dashboard: Use /api/metadata/database to display real-time database statistics
2. Monitoring Tools: Use /api/metadata to track uptime and version information
3. Setup Wizards: Use /api/metadata/api-key to retrieve credentials for SDK initialization
4. Health Checks: Combine with health endpoints to ensure backend availability