Projects API

Projects are the primary organizational unit in Connix. They provide isolated workspaces for your agents, environments, and resources.

Overview

Projects allow you to:

• Organize related agents and workflows
• Isolate resources and permissions
• Track usage and costs per project
• Manage team access and collaboration

Endpoints

Create Project

Create a new project in your organization.

POST /api/v1/projects

Request Body:

{
  "name": "string"
}

Parameters:

Field	Type	Required	Description
name	string	✅	Project name (3-50 characters, alphanumeric and hyphens)

Response:

{
  "id": 123,
  "name": "my-ai-project",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Example:

cURL

curl -X POST https://api.connix.io/api/v1/projects \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"name": "ml-training-pipeline"}'

JavaScript

const response = await fetch('https://api.connix.io/api/v1/projects', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key'
  },
  body: JSON.stringify({
    name: 'ml-training-pipeline'
  })
});

const project = await response.json();
console.log('Created project:', project);

Python

import requests

response = requests.post(
    'https://api.connix.io/api/v1/projects',
    headers={'X-API-Key': 'your-api-key'},
    json={'name': 'ml-training-pipeline'}
)

project = response.json()
print('Created project:', project)

Go

import (
    "bytes"
    "encoding/json"
    "net/http"
)

data := map[string]string{"name": "ml-training-pipeline"}
jsonData, _ := json.Marshal(data)

req, _ := http.NewRequest("POST", "https://api.connix.io/api/v1/projects", bytes.NewBuffer(jsonData))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "your-api-key")

client := &http.Client{}
resp, err := client.Do(req)

List Projects

Retrieve all projects in your organization.

GET /api/v1/projects

Query Parameters:

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20, max: 100)
search	string	Search projects by name
sort	string	Sort field (name, created_at, updated_at)
order	string	Sort order (asc, desc)

Response:

{
  "projects": [
    {
      "id": 123,
      "name": "ml-training-pipeline"
    },
    {
      "id": 124,
      "name": "data-processing-workflow"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Example:

cURL

curl -X GET "https://api.connix.io/api/v1/projects?limit=10&search=ml" \
  -H "X-API-Key: your-api-key"

JavaScript

const response = await fetch('https://api.connix.io/api/v1/projects?limit=10&search=ml', {
  headers: {
    'X-API-Key': 'your-api-key'
  }
});

const data = await response.json();
console.log('Projects:', data.projects);
console.log('Total:', data.pagination.total);

Python

import requests

params = {'limit': 10, 'search': 'ml'}
response = requests.get(
    'https://api.connix.io/api/v1/projects',
    headers={'X-API-Key': 'your-api-key'},
    params=params
)

data = response.json()
print('Projects:', data['projects'])
print('Total:', data['pagination']['total'])

Go

import (
    "encoding/json"
    "fmt"
    "net/http"
)

req, _ := http.NewRequest("GET", "https://api.connix.io/api/v1/projects?limit=10&search=ml", nil)
req.Header.Set("X-API-Key", "your-api-key")

client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

var data map[string]interface{}
json.NewDecoder(resp.Body).Decode(&data)
fmt.Println("Projects:", data["projects"])

Project Properties

Project Object

Field	Type	Description
id	integer	Unique project identifier
name	string	Project name
created_at	string	ISO 8601 timestamp of creation
updated_at	string	ISO 8601 timestamp of last update

Naming Rules

Project names must follow these rules:

• Length: 3-50 characters
• Characters: Alphanumeric characters and hyphens only
• Format: Must start and end with alphanumeric character
• Uniqueness: Must be unique within your organization

Valid Examples:

• ml-training-pipeline
• data-processing-v2
• customer-analytics
• test123

Invalid Examples:

• -invalid-start (starts with hyphen)
• invalid-end- (ends with hyphen)
• too_many_underscores (contains underscores)
• ab (too short)

Error Handling

Common Errors

Status	Error Code	Description
400	INVALID_PROJECT_NAME	Project name doesn’t meet requirements
400	PROJECT_NAME_TAKEN	Project name already exists
400	VALIDATION_ERROR	Request validation failed
401	UNAUTHORIZED	Invalid or missing API key
403	FORBIDDEN	Insufficient permissions
429	RATE_LIMIT_EXCEEDED	Too many requests

Error Response Examples

Invalid Project Name:

{
  "error": {
    "code": "INVALID_PROJECT_NAME",
    "message": "Project name must be 3-50 characters long and contain only alphanumeric characters and hyphens",
    "details": {
      "field": "name",
      "value": "ab",
      "issue": "too short"
    }
  }
}

Project Name Already Exists:

{
  "error": {
    "code": "PROJECT_NAME_TAKEN",
    "message": "A project with this name already exists",
    "details": {
      "field": "name",
      "value": "existing-project"
    }
  }
}

Usage Examples

Creating a Data Science Project

JavaScript

import { ConnixClient } from '@connix/sdk';

const client = new ConnixClient({ apiKey: 'your-api-key' });

async function setupDataScienceProject() {
  try {
    // Create the main project
    const project = await client.createProject({
      name: 'customer-churn-analysis'
    });

    console.log(`✅ Created project: ${project.name} (ID: ${project.id})`);

    // You can now launch agents in this project
    const agent = await client.launchAgent({
      name: 'data-preprocessor',
      projectId: project.id
    });

    console.log(`🚀 Launched agent: ${agent.message}`);

    return project;

  } catch (error) {
    if (error.code === 'PROJECT_NAME_TAKEN') {
      console.log('Project already exists, using existing project');
      // Handle existing project logic
    } else {
      console.error('Failed to create project:', error.message);
      throw error;
    }
  }
}

const project = await setupDataScienceProject();

Python

import connix
from connix.exceptions import ProjectNameTakenError

client = connix.Client()

def setup_data_science_project():
    try:
        # Create the main project
        project = client.create_project(name='customer-churn-analysis')
        print(f'✅ Created project: {project.name} (ID: {project.id})')

        # You can now launch agents in this project
        agent = client.launch_agent(
            name='data-preprocessor',
            project_id=project.id
        )
        print(f'🚀 Launched agent: {agent.message}')

        return project

    except ProjectNameTakenError:
        print('Project already exists, using existing project')
        # Handle existing project logic
        projects = client.list_projects(search='customer-churn-analysis')
        return projects.projects[0]
    except Exception as error:
        print(f'Failed to create project: {error}')
        raise

project = setup_data_science_project()

Listing and Filtering Projects

JavaScript

async function manageProjects() {
  // List all projects
  const allProjects = await client.listProjects();
  console.log(`Total projects: ${allProjects.pagination.total}`);

  // Search for machine learning projects
  const mlProjects = await client.listProjects({
    search: 'ml',
    limit: 5
  });

  // List projects sorted by creation date
  const recentProjects = await client.listProjects({
    sort: 'created_at',
    order: 'desc',
    limit: 10
  });

  // Display project information
  recentProjects.projects.forEach(project => {
    console.log(`Project: ${project.name} (ID: ${project.id})`);
  });

  return {
    total: allProjects.pagination.total,
    ml: mlProjects.projects.length,
    recent: recentProjects.projects
  };
}

const stats = await manageProjects();

Python

def manage_projects():
    # List all projects
    all_projects = client.list_projects()
    print(f'Total projects: {all_projects.pagination.total}')

    # Search for machine learning projects
    ml_projects = client.list_projects(search='ml', limit=5)

    # List projects sorted by creation date
    recent_projects = client.list_projects(
        sort='created_at',
        order='desc',
        limit=10
    )

    # Display project information
    for project in recent_projects.projects:
        print(f'Project: {project.name} (ID: {project.id})')

    return {
        'total': all_projects.pagination.total,
        'ml': len(ml_projects.projects),
        'recent': recent_projects.projects
    }

stats = manage_projects()

Best Practices

Project Organization

• Use descriptive, consistent naming conventions
• Group related workflows in the same project
• Create separate projects for different environments (dev, staging, prod)
• Use project names that reflect business domains or use cases

Resource Management

• Monitor project resource usage regularly
• Clean up unused projects to avoid unnecessary costs
• Use meaningful project names for easier identification
• Document project purposes and ownership

Security

• Limit project access to necessary team members
• Regularly audit project permissions
• Use separate projects for sensitive workloads
• Implement proper naming conventions to avoid data leaks

Related Resources

• Agents API - Launch agents within projects
• Authentication - API authentication methods
• Error Handling - Complete error reference