Metadata

The NeoSpace AI API supports the use of metadata on various resources, allowing you to store additional and customized information along with your objects. This functionality is extremely useful for tracking, categorization, and integration with your internal systems.

What is metadata?

Metadata are key-value pairs that you can attach to NeoSpace AI resources. They are useful for:

• Storing application-specific information
• Categorizing and organizing resources
• Tracking information across systems
• Implementing custom business logic

Metadata format

Metadata is represented as a simple JSON object, where keys and values are strings:

{
  "metadata": {
    "internal_id": "12345",
    "department": "finance",
    "project": "q4_analysis",
    "user_reference": "client_abc"
  }
}

Limitations

• Metadata keys can be up to 40 characters long
• Values can be up to 500 characters long
• A resource can have a maximum of 50 key-value pairs
• Only strings are allowed as values (no nested objects or arrays)

Resources that support metadata

The following NeoSpace AI API resources support metadata:

• API Keys (/v1/api-keys)
• Experts (/v1/experts)
• Chats (/v1/chats)
• Projects (/v1/projects)

Adding metadata

You can add metadata when creating or updating a resource:

// Creating a new chat with metadata
const response = await fetch('https://api.neospace.ai/v1/chats', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [
      { role: 'user', content: 'Analyze this financial report' }
    ],
    model: 'neo-financial-1',
    metadata: {
      client_id: '89012',
      case_number: 'FIN-2023-0456',
      priority: 'high'
    }
  })
});

Updating metadata

You can update the metadata of an existing resource:

// Updating metadata of an existing expert
const response = await fetch('https://api.neospace.ai/v1/experts/exp_123456', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    metadata: {
      version: '2.0',
      last_updated_by: '[email protected]'
    }
  })
});

Querying by metadata

You can filter resources based on their metadata:

// Searching for chats with specific metadata
const response = await fetch('https://api.neospace.ai/v1/chats?metadata[client_id]=89012', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

Common use cases

Integration with internal systems

Use metadata to link NeoSpace AI resources to your internal systems:

{
  "metadata": {
    "crm_id": "customer_456",
    "ticket_id": "support_789",
    "internal_user_id": "emp_101"
  }
}

Categorization

Organize your resources with custom categories:

{
  "metadata": {
    "department": "wealth_management",
    "use_case": "portfolio_analysis",
    "client_segment": "premium"
  }
}

Version tracking

Keep track of versions and changes:

{
  "metadata": {
    "version": "1.2.0",
    "created_by": "[email protected]",
    "last_modified": "2023-10-15",
    "approved_by": "[email protected]"
  }
}

Cost analysis

Allocate costs to different cost centers or projects:

{
  "metadata": {
    "cost_center": "cc_12345",
    "project_code": "p_67890",
    "budget_quarter": "Q4_2023"
  }
}

Best practices

Naming standardization

Establish a consistent standard for your metadata keys:

• Use snake_case or camelCase consistently
• Define prefixes for different categories (e.g., client_, internal_)
• Document your metadata schema for team reference

Security

• Don't store sensitive information in metadata
• Remember that metadata is visible to all users with access to the resource
• Consider using IDs or references instead of actual data when appropriate

Performance

• Keep metadata concise to avoid overhead
• Consider which metadata you actually need to query
• For rarely accessed data, consider storing it in your own systems

Complete example

Here's a complete example of using metadata in a workflow:

// 1. Create an expert with metadata
const expertResponse = await fetch('https://api.neospace.ai/v1/experts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Financial Analyst',
    description: 'Specialist in financial statement analysis',
    context: 'You are a financial analysis expert...',
    metadata: {
      department: 'financial_analysis',
      creator: '[email protected]',
      version: '1.0'
    }
  })
});

const expert = await expertResponse.json();
const expertId = expert.id;

// 2. Create a chat using the expert and adding related metadata
const chatResponse = await fetch('https://api.neospace.ai/v1/chats', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    expert_ids: [expertId],
    messages: [
      { role: 'user', content: 'Analyze this balance sheet' }
    ],
    metadata: {
      client_id: 'client_12345',
      report_type: 'quarterly_review',
      analyst: '[email protected]',
      related_expert: expertId
    }
  })
});

// 3. Later, fetch all chats related to this client
const clientChats = await fetch('https://api.neospace.ai/v1/chats?metadata[client_id]=client_12345', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});