GraphQL API Reference¶

AIDDDMAP provides a powerful GraphQL API for flexible data querying and manipulation. This guide covers the available queries, mutations, and subscriptions.

Getting Started¶

Base URL¶

https://api.aidddmap.com/graphql

Authentication¶

All GraphQL requests require authentication using a Bearer token:

Authorization: Bearer <your_token>

Schema Types¶

User¶

type User {
  id: ID!
  name: String
  email: String
  role: UserRole!
  createdAt: DateTime!
  updatedAt: DateTime!
}

enum UserRole {
  USER
  ADMIN
  DEVELOPER
}

Dataset¶

type Dataset {
  id: ID!
  name: String!
  description: String
  owner: User!
  isEncrypted: Boolean!
  encryptionType: EncryptionType
  createdAt: DateTime!
  updatedAt: DateTime!
}

enum EncryptionType {
  NONE
  BASIC
  FHE
  ZK
}

Agent¶

type Agent {
  id: ID!
  name: String!
  description: String
  creator: User!
  capabilities: [Capability!]!
  status: AgentStatus!
}

enum AgentStatus {
  ACTIVE
  INACTIVE
  TRAINING
}

Queries¶

Get User Profile¶

query GetUserProfile {
  me {
    id
    name
    email
    role
  }
}

List Datasets¶

query ListDatasets($first: Int, $after: String) {
  datasets(first: $first, after: $after) {
    edges {
      node {
        id
        name
        description
        isEncrypted
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Get Agent Details¶

query GetAgent($id: ID!) {
  agent(id: $id) {
    id
    name
    description
    capabilities
    status
  }
}

Mutations¶

Create Dataset¶

mutation CreateDataset($input: CreateDatasetInput!) {
  createDataset(input: $input) {
    dataset {
      id
      name
      description
    }
  }
}

Deploy Agent¶

mutation DeployAgent($input: DeployAgentInput!) {
  deployAgent(input: $input) {
    agent {
      id
      status
    }
  }
}

Update Encryption Settings¶

mutation UpdateEncryption($input: UpdateEncryptionInput!) {
  updateEncryption(input: $input) {
    dataset {
      id
      isEncrypted
      encryptionType
    }
  }
}

Subscriptions¶

Dataset Updates¶

subscription OnDatasetUpdate($id: ID!) {
  datasetUpdated(id: $id) {
    id
    name
    updatedAt
  }
}

Agent Status Changes¶

subscription OnAgentStatusChange($id: ID!) {
  agentStatusChanged(id: $id) {
    id
    status
  }
}

Error Handling¶

GraphQL errors follow this structure:

{
  "errors": [
    {
      "message": "Error message",
      "path": ["query", "field"],
      "extensions": {
        "code": "ERROR_CODE"
      }
    }
  ]
}

Common error codes:

UNAUTHORIZED: Authentication required
FORBIDDEN: Insufficient permissions
NOT_FOUND: Resource not found
VALIDATION_ERROR: Invalid input

Rate Limiting¶

1000 requests per hour per API token
Responses include rate limit headers:
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Best Practices¶

Use fragments for reusable fields
Request only needed fields
Implement proper error handling
Use pagination for large datasets
Consider caching frequently used queries

Tools and Resources¶

GraphQL Playground: Available at https://api.aidddmap.com/graphql
Schema Documentation: Auto-generated in the Playground
Client Libraries:
Apollo Client for JavaScript/TypeScript
GraphQL Code Generator for type generation