DevTeam.ai
GitHubGet Started

GraphQL API Reference

Complete API schema documentation for programmatic access to DevTeam.ai.

API Endpoint:

https://devteam-api.finhub.workers.dev/graphql

Authentication

All API requests require authentication via Bearer token:

typescript
const response = await fetch('https://devteam-api.finhub.workers.dev/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({ query, variables })
})

Schema Overview

Core Types

Project

graphql
type Project {
  id: ID!
  name: String!
  description: String
  status: ProjectStatus!
  ownerId: String!
  estimatedHours: Int!
  actualHours: Int!
  createdAt: DateTime!
  updatedAt: DateTime!
}


enum ProjectStatus {
  PLANNING
  IN_PROGRESS
  REVIEW
  COMPLETED
  PAUSED
  CANCELLED
}

Agent

graphql
type Agent {
  id: ID!
  projectId: String!
  role: AgentRole!
  name: String!
  status: AgentStatus!
  createdAt: DateTime!
}


enum AgentRole {
  PROJECT_MANAGER
  CHIEF_ARCHITECT
  ENGINEERING_MANAGER
  CODE_REVIEWER
  UX_DESIGNER
  FRONTEND_SPECIALIST
  ANIMATION_SPECIALIST
  BACKEND_DEVELOPER
  DATABASE_ARCHITECT
  MOBILE_DEVELOPER
  QA_SPECIALIST
  SECURITY_ANALYST
  FINTECH_SPECIALIST
  AI_EXPERT
  DEVOPS_ENGINEER
}


enum AgentStatus {
  IDLE
  WORKING
  WAITING
  BLOCKED
  COMPLETED
}

Task

graphql
type Task {
  id: ID!
  projectId: String!
  agentId: String
  title: String!
  description: String
  status: TaskStatus!
  priority: TaskPriority!
  createdAt: DateTime!
}


enum TaskStatus {
  PENDING
  IN_PROGRESS
  REVIEW
  COMPLETED
  FAILED
}


enum TaskPriority {
  LOW
  MEDIUM
  HIGH
  CRITICAL
}

Knowledge Entry

graphql
type KnowledgeEntry {
  id: ID!
  type: KnowledgeType!
  title: String!
  content: String!
  metadata: KnowledgeMetadata!
  createdAt: String!
  updatedAt: String!
}


enum KnowledgeType {
  CODE_PATTERN
  ARCHITECTURE_DECISION
  PROJECT_CONTEXT
  DOMAIN_EXPERTISE
  AGENT_LEARNING
  ERROR_RESOLUTION
  API_PATTERN
  SECURITY_PATTERN
  PERFORMANCE_OPTIMIZATION
}


type KnowledgeMetadata {
  projectId: String
  agentRole: String
  tags: [String!]!
  language: String
  framework: String
  usageCount: Int!
  source: String
}

Queries

Get Current User

graphql
query {
  me {
    id
    email
    name
    organizationId
    role
  }
}

Get Project

graphql
query GetProject($id: String!) {
  project(id: $id) {
    id
    name
    description
    status
    estimatedHours
    actualHours
    createdAt
    updatedAt
  }
}

List Projects

graphql
query {
  projects {
    id
    name
    status
    createdAt
  }
}

Get Project Agents

graphql
query GetAgents($projectId: String!) {
  agents(projectId: $projectId) {
    id
    role
    name
    status
    createdAt
  }
}

Get Project Tasks

graphql
query GetTasks($projectId: String!) {
  tasks(projectId: $projectId) {
    id
    title
    description
    status
    priority
    agentId
    createdAt
  }
}

Search Knowledge Base

graphql
query SearchKnowledge(
  $query: String!,
  $type: KnowledgeType,
  $language: String,
  $limit: Int
) {
  searchKnowledge(
    query: $query,
    type: $type,
    language: $language,
    limit: $limit
  ) {
    entry {
      id
      type
      title
      content
      metadata {
        tags
        language
        framework
      }
    }
    score
    relevance
  }
}

Get Knowledge Stats

graphql
query {
  knowledgeStats {
    totalEntries
    byType
    byRole
  }
}

Mutations

Create Project

graphql
mutation CreateProject(
  $name: String!,
  $description: String,
  $requirements: String!
) {
  createProject(
    name: $name,
    description: $description,
    requirements: $requirements
  ) {
    id
    name
    status
    createdAt
  }
}

Spawn Agent

graphql
mutation SpawnAgent(
  $projectId: String!,
  $role: AgentRole!
) {
  spawnAgent(
    projectId: $projectId,
    role: $role
  ) {
    id
    role
    name
    status
  }
}

Message Agent

graphql
mutation MessageAgent(
  $agentId: String!,
  $content: String!
) {
  messageAgent(
    agentId: $agentId,
    content: $content
  )
}

Create Task

graphql
mutation CreateTask(
  $projectId: String!,
  $title: String!,
  $description: String,
  $priority: TaskPriority!,
  $agentRole: AgentRole
) {
  createTask(
    projectId: $projectId,
    title: $title,
    description: $description,
    priority: $priority,
    agentRole: $agentRole
  ) {
    id
    title
    status
    priority
  }
}

Update Task

graphql
mutation UpdateTask(
  $id: String!,
  $status: TaskStatus,
  $priority: TaskPriority
) {
  updateTask(
    id: $id,
    status: $status,
    priority: $priority
  ) {
    id
    status
    priority
    updatedAt
  }
}

Assign Task to Agent

graphql
mutation AssignTask(
  $taskId: String!,
  $agentId: String!
) {
  assignTaskToAgent(
    taskId: $taskId,
    agentId: $agentId
  ) {
    id
    agentId
    status
  }
}

Store Knowledge

graphql
mutation StoreKnowledge(
  $type: KnowledgeType!,
  $title: String!,
  $content: String!,
  $projectId: String,
  $tags: [String!],
  $language: String
) {
  storeKnowledge(
    type: $type,
    title: $title,
    content: $content,
    projectId: $projectId,
    tags: $tags,
    language: $language
  ) {
    id
    title
    type
  }
}

Evaluate PRD

graphql
mutation EvaluatePRD(
  $projectId: String!,
  $content: String!
) {
  evaluatePRD(
    projectId: $projectId,
    content: $content
  ) {
    isValid
    score
    hasProblemStatement
    hasUserStories
    hasAcceptanceCriteria
    completenessScore
    clarityScore
    implementabilityScore
    missingElements
    recommendations
    summary
  }
}

Complete Example

Here's a complete workflow using the API:

typescript
const DEVTEAM_API = 'https://devteam-api.finhub.workers.dev/graphql';
const API_KEY = process.env.DEVTEAM_API_KEY;


async function graphql(query: string, variables?: Record<string, any>) {
  const response = await fetch(DEVTEAM_API, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({ query, variables })
  });


  const { data, errors } = await response.json();
  if (errors) throw new Error(errors[0].message);
  return data;
}


// 1. Create a new project
const { createProject: project } = await graphql(`
  mutation CreateProject($name: String!, $requirements: String!) {
    createProject(name: $name, requirements: $requirements) {
      id
      name
      status
    }
  }
`, {
  name: 'My New App',
  requirements: 'Build a React dashboard with real-time updates'
});


// 2. Spawn specialized agents
const agents = await Promise.all([
  AgentRole.PROJECT_MANAGER,
  AgentRole.CHIEF_ARCHITECT,
  AgentRole.FRONTEND_SPECIALIST
].map(role =>
  graphql(`
    mutation SpawnAgent($projectId: String!, $role: AgentRole!) {
      spawnAgent(projectId: $projectId, role: $role) {
        id
        role
        name
      }
    }
  `, { projectId: project.id, role })
));


// 3. Create tasks
const { createTask: task } = await graphql(`
  mutation CreateTask($projectId: String!, $title: String!, $priority: TaskPriority!) {
    createTask(projectId: $projectId, title: $title, priority: $priority) {
      id
      title
      status
    }
  }
`, {
  projectId: project.id,
  title: 'Design component architecture',
  priority: 'HIGH'
});


// 4. Assign task to an agent
await graphql(`
  mutation AssignTask($taskId: String!, $agentId: String!) {
    assignTaskToAgent(taskId: $taskId, agentId: $agentId) {
      id
      status
    }
  }
`, {
  taskId: task.id,
  agentId: agents[1].spawnAgent.id // Chief Architect
});


console.log('Project created and agents are working!');

Error Handling

All API errors follow this format:

json
{
  "errors": [
    {
      "message": "Not authorized",
      "path": ["projects"],
      "extensions": {
        "code": "UNAUTHORIZED"
      }
    }
  ]
}

Common error codes:

  • UNAUTHORIZED - Invalid or missing API key
  • FORBIDDEN - Insufficient permissions
  • NOT_FOUND - Resource does not exist
  • VALIDATION_ERROR - Invalid input
  • RATE_LIMIT_EXCEEDED - Too many requests

Next Steps

Authentication

Learn about API keys, scopes, and security

Rate Limiting

Understand rate limits and quotas