API Documentation

curl -X POST https://arca.build/api/v1/tables/upsert \
  -H "Authorization: Bearer <your-arca-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"tableName": "meals", "data": {...}}'

{
  "tableName": "workouts",
  "columns": [
    { "name": "exercise", "type": "VARCHAR" },
    { "name": "duration_minutes", "type": "INTEGER" },
    { "name": "intensity", "type": "VARCHAR" }
  ],
  "data": {
    "exercise": "Running",
    "duration_minutes": 30,
    "intensity": "moderate"
  },
  "skill": {
    "description": "Tracks workout sessions and fitness activities",
    "examples": [
      "SELECT * FROM workouts WHERE intensity = 'high'",
      "SELECT exercise, AVG(duration_minutes) FROM workouts GROUP BY exercise"
    ],
    "relationships": ["Related to health_metrics table"],
    "notes": "Track all exercise sessions with duration and intensity"
  }
}

{
  "tableName": "workouts",
  "data": {
    "exercise": "Cycling",
    "duration_minutes": 45,
    "intensity": "high"
  }
}

// Time-based filter (last 7 days)
{
  "tableName": "meals",
  "filters": {
    "dateColumn": "created_at",
    "daysAgo": 7
  },
  "orderBy": "created_at DESC",
  "limit": 10
}

// Time-based filter (last 48 hours)
{
  "tableName": "meals",
  "filters": {
    "dateColumn": "created_at",
    "hoursAgo": 48
  }
}

// Custom WHERE clause
{
  "tableName": "meals",
  "filters": {
    "customWhere": "calories > 500 AND meal_type = 'dinner'"
  }
}

// Aggregations
{
  "tableName": "meals",
  "aggregations": {
    "sum": ["calories"],
    "avg": ["calories"],
    "count": ["id"],
    "max": ["calories"],
    "min": ["calories"]
  }
}

// Custom SQL query
{
  "tableName": "meals",
  "query": "SELECT meal_type, SUM(calories) as total FROM meals GROUP BY meal_type"
}

{
  "tableName": "meals",
  "updates": {
    "calories": 900,
    "meal_type": "dinner"
  },
  "where": "id = 5"
}

curl -X GET https://arca.build/api/v1/tables/list \
  -H "Authorization: Bearer user_01K742..."

// Response:
{
  "success": true,
  "userId": "user_01K742...",
  "tableCount": 2,
  "tables": [
    {
      "name": "meals",
      "size": 4096,
      "lastModified": "2025-01-10T12:00:00Z",
      "s3Path": "s3://arca-user-vault/user_01K742.../tables/meals.parquet"
    }
  ]
}

curl -X GET https://arca.build/api/v1/tables/skills \
  -H "Authorization: Bearer user_01K742..."

// Response includes full markdown content for each table:
{
  "success": true,
  "userId": "user_01K742...",
  "skillCount": 11,
  "skills": [
    {
      "tableName": "meals",
      "skill": "---\nname: meals\ndescription: Tracks daily meal consumption for nutrition analysis\ntype: data-table\nschema_version: 1.0.0\n---\n\n# meals\n\n## Purpose\nTracks daily meal consumption for nutrition analysis\n\n## Schema\n| Column | Type | Nullable |\n|--------|------|----------|\n| id | INTEGER | No |\n| food | VARCHAR | Yes |\n| calories | INTEGER | Yes |\n| meal_type | VARCHAR | Yes |\n| created_at | TIMESTAMP | No |\n\n## Usage Examples\n\n```sql\nSELECT * FROM meals WHERE calories > 500\n```\n\n```sql\nSELECT meal_type, SUM(calories) FROM meals GROUP BY meal_type\n```\n\n## Relationships\n- Related to nutrition_goals table\n\n## Notes\nUse meal_type field to categorize meals",
      "success": true
    },
    {
      "tableName": "weight_logs",
      "skill": "---\nname: weight_logs\ndescription: Daily weight tracking for health monitoring and fitness goals\n...",
      "success": true
    }
  ]
}

curl -X GET https://arca.build/api/v1/tables/schemas \
  -H "Authorization: Bearer user_01K742..."

// Response:
{
  "success": true,
  "tableCount": 1,
  "schemas": [
    {
      "tableName": "meals",
      "columns": [
        { "name": "id", "type": "INTEGER", "nullable": false },
        { "name": "food", "type": "VARCHAR", "nullable": true },
        { "name": "calories", "type": "INTEGER", "nullable": true },
        { "name": "created_at", "type": "TIMESTAMP", "nullable": false }
      ]
    }
  ]
}

curl -X GET "https://arca.build/api/v1/tables/export?tableName=meals" \
  -H "Authorization: Bearer user_01K742..." \
  --output meals.parquet

// When creating/upserting a table
{
  "tableName": "weight_logs",
  "columns": [
    { "name": "weight", "type": "DOUBLE" },
    { "name": "log_date", "type": "DATE" },
    { "name": "notes", "type": "VARCHAR" }
  ],
  "data": {
    "weight": 185.5,
    "log_date": "2025-01-14",
    "notes": "Morning weigh-in after workout"
  },
  "skill": {
    "description": "Daily weight tracking for health monitoring and fitness goals",
    "examples": [
      "SELECT * FROM weight_logs ORDER BY log_date DESC LIMIT 30",
      "SELECT AVG(weight) as avg_weight FROM weight_logs WHERE log_date > NOW() - INTERVAL '7 days'",
      "SELECT log_date, weight, (weight - LAG(weight) OVER (ORDER BY log_date)) as daily_change FROM weight_logs ORDER BY log_date DESC LIMIT 10"
    ],
    "relationships": [
      "Related to exercises for tracking fitness progress"
    ],
    "notes": "Record weight consistently at the same time of day for accurate tracking. Weight should be in pounds or kilograms based on preference."
  }
}

curl -X GET https://arca.build/api/v1/tables/meals/skill \
  -H "Authorization: Bearer user_01K742..."

// Response:
{
  "success": true,
  "tableName": "meals",
  "skill": "---\nname: meals\ndescription: Tracks daily meal consumption...\n---\n\n# meals\n\n## Purpose\n..."
}

// Update with structured metadata
{
  "skill": {
    "description": "Updated description for meal tracking",
    "examples": [
      "SELECT * FROM meals WHERE meal_type = 'dinner'",
      "SELECT DATE(created_at), COUNT(*) FROM meals GROUP BY DATE(created_at)"
    ],
    "relationships": [
      "Related to nutrition_goals and daily_stats tables"
    ],
    "notes": "Track all meals with accurate calorie counts for best results"
  }
}

// Or update with raw markdown
{
  "content": "---\nname: meals\n---\n\n# My Custom Skill\n\nCustom markdown content..."
}

---
name: meals
description: Tracks daily meal consumption for nutrition analysis
type: data-table
schema_version: 1.0.0
---

# meals

## Purpose
Tracks daily meal consumption for nutrition analysis

## Schema
| Column | Type | Nullable |
|--------|------|----------|
| id | INTEGER | No |
| food | VARCHAR | Yes |
| calories | INTEGER | Yes |
| meal_type | VARCHAR | Yes |
| created_at | TIMESTAMP | No |
| updated_at | TIMESTAMP | No |

## Usage Examples

\`\`\`sql
SELECT * FROM meals WHERE calories > 500
\`\`\`

\`\`\`sql
SELECT meal_type, SUM(calories) FROM meals GROUP BY meal_type
\`\`\`

## Relationships
- Related to nutrition_goals table for tracking daily targets
- Links with user_profile for dietary preferences

## Notes
Use meal_type field to filter breakfast/lunch/dinner. Calories should be recorded as integers.

import { ArcaTableClient } from '@/utils/arca-table-client';

const client = new ArcaTableClient('user_01K742...', 'https://arca.build');

// Create table with skill metadata
await client.upsert({
  tableName: 'workouts',
  columns: [
    { name: 'exercise', type: 'VARCHAR' },
    { name: 'duration_minutes', type: 'INTEGER' }
  ],
  data: { exercise: 'Running', duration_minutes: 30 },
  skill: {
    description: 'Tracks workout sessions and fitness activities',
    examples: [
      'SELECT * FROM workouts WHERE intensity = "high"',
      'SELECT exercise, AVG(duration_minutes) FROM workouts GROUP BY exercise'
    ],
    relationships: ['Related to health_metrics table'],
    notes: 'Track all exercise sessions with duration and intensity'
  }
});

// Get the skill for a table
const skill = await client.getSkill('workouts');
console.log(skill.skill); // Markdown content

// Update the skill
await client.updateSkill('workouts', {
  skill: {
    description: 'Enhanced workout tracking with detailed metrics',
    examples: ['SELECT * FROM workouts WHERE created_at > NOW() - INTERVAL "7 days"'],
    relationships: ['Related to health_metrics and nutrition tables'],
    notes: 'Include warmup and cooldown times in duration'
  }
});

// Example: Journal entry with skill metadata
{
  "tableName": "journal_entries",
  "text": "Today was a productive day. Finished the project proposal and went for a run.",
  "metadata": {
    "category": "personal",
    "mood": "positive",
    "tags": "productivity,exercise"
  },
  "skill": {
    "description": "Personal journal entries tracking daily activities and reflections",
    "metadata_fields": [
      {
        "name": "category",
        "type": "string",
        "description": "Type of entry",
        "examples": ["personal", "work", "health"]
      },
      {
        "name": "mood",
        "type": "string",
        "description": "Emotional state",
        "examples": ["positive", "neutral", "negative"]
      },
      {
        "name": "tags",
        "type": "string",
        "description": "Comma-separated tags"
      }
    ],
    "search_examples": [
      "Find productive days",
      "Show entries about exercise"
    ],
    "filter_examples": [
      "mood = 'positive'",
      "category = 'work'"
    ],
    "notes": "Journal entries are searchable by semantic meaning"
  }
}

// Example: Recipe collection
{
  "tableName": "recipes",
  "text": "Grandma's chocolate chip cookies - soft and chewy with a hint of vanilla",
  "metadata": {
    "category": "dessert",
    "difficulty": "easy",
    "cuisine": "American",
    "tags": "baking,cookies,family"
  }
}

// Example: Bookmarks/Links
{
  "tableName": "bookmarks",
  "text": "How to Build a Search Engine - comprehensive guide to information retrieval systems",
  "metadata": {
    "category": "technical",
    "url": "https://example.com/search-guide",
    "tags": "programming,search,tutorial"
  }
}

// Example: Code Snippets
{
  "tableName": "code_snippets",
  "text": "React hook for debouncing user input in search boxes",
  "metadata": {
    "language": "typescript",
    "category": "react",
    "tags": "hooks,performance,search"
  }
}

// Example: Research Notes
{
  "tableName": "research_notes",
  "text": "Study on machine learning bias mitigation techniques - focuses on fairness in AI models",
  "metadata": {
    "category": "ai-ethics",
    "source": "Journal of AI Research",
    "tags": "ml,fairness,bias"
  }
}

// Search journal entries
{
  "tableName": "journal_entries",
  "query": "days when I felt accomplished",
  "limit": 5,
  "filter": "mood = 'positive'"
}

// Search recipes
{
  "tableName": "recipes",
  "query": "quick desserts",
  "limit": 5,
  "filter": "difficulty = 'easy'"
}

// Response includes similarity scores
{
  "success": true,
  "results": [
    {
      "text": "Grandma's chocolate chip cookies",
      "_distance": 0.15,
      "metadata": { "category": "dessert", "difficulty": "easy" },
      "created_at": "2025-01-10T10:30:00Z"
    }
  ]
}

curl -X GET https://arca.build/api/v1/vectors/list \
  -H "Authorization: Bearer user_01K742..."

// Export via API
curl -X POST https://arca.build/api/v1/vectors/export \
  -H "Authorization: Bearer user_01K742..." \
  -H "Content-Type: application/json" \
  -d '{"tableName": "recipes"}' \
  --output recipes.csv

// Add vector with skill metadata (creates SKILL.md automatically)
{
  "tableName": "recipes",
  "text": "Grandma's chocolate chip cookies - soft and chewy",
  "metadata": {
    "category": "dessert",
    "difficulty": "easy",
    "cuisine": "American",
    "tags": "baking,cookies"
  },
  "skill": {
    "description": "Personal recipe collection with search and filtering",
    "metadata_fields": [
      {
        "name": "category",
        "type": "string",
        "description": "Recipe category",
        "examples": ["dessert", "main", "appetizer", "side"]
      },
      {
        "name": "difficulty",
        "type": "string",
        "description": "Difficulty level",
        "examples": ["easy", "medium", "hard"]
      },
      {
        "name": "cuisine",
        "type": "string",
        "description": "Cuisine type",
        "examples": ["Italian", "Asian", "Mexican", "American"]
      },
      {
        "name": "tags",
        "type": "string",
        "description": "Comma-separated tags for detailed categorization"
      }
    ],
    "search_examples": [
      "Find chocolate desserts",
      "Quick weeknight dinners",
      "Italian pasta recipes"
    ],
    "filter_examples": [
      "difficulty = 'easy'",
      "category = 'dessert'",
      "cuisine = 'Italian' AND difficulty = 'easy'"
    ],
    "notes": "Use tags for detailed categorization. Difficulty levels help filter by cooking complexity."
  }
}

// GET /api/v1/vectors/[tableName]/skill - Get skill for a specific vector table
curl -X GET https://arca.build/api/v1/vectors/recipes/skill \
  -H "Authorization: Bearer user_01K742..."

// Response includes markdown content:
{
  "success": true,
  "tableName": "recipes",
  "skill": "---\nname: recipes\ndescription: Personal recipe collection...\n---\n\n# recipes\n\n## Purpose\n..."
}

// PUT /api/v1/vectors/[tableName]/skill - Update skill metadata
curl -X PUT https://arca.build/api/v1/vectors/recipes/skill \
  -H "Authorization: Bearer user_01K742..." \
  -H "Content-Type: application/json" \
  -d '{
    "skill": {
      "description": "Updated recipe collection with new categorization",
      "metadata_fields": [...],
      "search_examples": ["New search example"],
      "notes": "Updated usage notes"
    }
  }'

curl -X GET https://arca.build/api/v1/vectors/skills \
  -H "Authorization: Bearer user_01K742..."

// Response includes full markdown for all vector collections
{
  "success": true,
  "userId": "user_01K742...",
  "skillCount": 5,
  "skills": [
    {
      "tableName": "recipes",
      "skill": "---\nname: recipes\ndescription: Personal recipe collection\ntype: vector-collection\n---\n\n# recipes\n\n## Purpose\n...\n\n## Metadata Fields\n- **category** (string): Recipe category\n...",
      "success": true
    },
    {
      "tableName": "bookmarks",
      "skill": "---\nname: bookmarks\ndescription: Saved links and articles\ntype: vector-collection\n---\n...",
      "success": true
    }
  ]
}

pip install arca-ai-vault

from arca import ArcaTableClient, TableColumn, SkillMetadata

client = ArcaTableClient(user_id="your-api-key")

# Upsert with skill metadata
client.upsert(
    table_name="meals",
    columns=[
        TableColumn("food", "VARCHAR"),
        TableColumn("calories", "INTEGER")
    ],
    data={"food": "Grilled Chicken", "calories": 165},
    skill=SkillMetadata(
        description="Tracks daily meals and nutrition",
        examples=["SELECT * FROM meals WHERE calories > 200"]
    )
)

# Query data
results = client.query(
    table_name="meals",
    filters={"daysAgo": 7},
    order_by="calories DESC",
    limit=10
)

# List tables and get schemas
tables = client.list_tables()
schemas = client.get_schemas()

from arca import ArcaVectorClient, VectorSkillMetadata, MetadataField

client = ArcaVectorClient(user_id="your-api-key")

# Add with automatic embedding
client.add(
    table_name="journal_entries",
    text="Today was incredibly productive.",
    metadata={"category": "personal", "mood": "positive"},
    skill=VectorSkillMetadata(
        description="Personal journal entries with mood tracking",
        metadata_fields=[
            MetadataField("category", "string", "Entry category"),
            MetadataField("mood", "string", "Emotional state")
        ]
    )
)

# Search semantically
results = client.search(
    table_name="journal_entries",
    query="productive and successful days",
    limit=5,
    filter="category = 'personal'"
)

# List vector tables
tables = client.list_tables()

from arca import get_all_skills

# Fetch all skills (both table and vector) in one call
all_skills = get_all_skills(user_id="your-api-key")

print(f"Total skills: {len(all_skills['skills'])}")
print(f"Tables: {all_skills['tableSkillCount']}")
print(f"Vectors: {all_skills['vectorSkillCount']}")

# Filter by type if needed
table_skills = [s for s in all_skills['skills'] if s['type'] == 'table']
vector_skills = [s for s in all_skills['skills'] if s['type'] == 'vector']