Skip to main content

​
Overview

Consuelo provides a dedicated GraphQL API for internal team operations. This guide covers how to access and use the internal Consuelo instance.

​
Internal Instance

Workspace ID: <your-workspace-id>

​
Endpoints

EndpointURL
GraphQLhttps://<your-internal-domain>/graphql
Metadatahttps://<your-internal-domain>/metadata
Apphttps://<your-internal-domain>

​
Authentication

Use your internal API key: 
Authorization: Bearer YOUR_INTERNAL_API_KEY
Get your key from Settings → APIs & Webhooks in the internal workspace.

​
Testing the API

​
Using cURL

curl -X POST https://<your-internal-domain>/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ currentUser { id email } }"}'

​
Using GraphQL Playground

  1. Open https://<your-internal-domain>/graphql
  2. Click HTTP HEADERS at the bottom
  3. Add your authorization header: 
    {
  "Authorization": "Bearer YOUR_API_KEY"
}
  4. Run queries in the editor

​
Using Postman

  1. Set request type: POST
  2. URL: https://<your-internal-domain>/graphql
  3. Headers:
    • Authorization: Bearer YOUR_API_KEY
    • Content-Type: application/json
  4. Body (raw JSON): 
    {
  "query": "{ people(first: 10) { edges { node { id email } } } }"
}

​
Common Query Patterns

​
Query People

query GetPeople($first: Int!) {
  people(first: $first) {
    edges {
      node {
        id
        email
        firstName
        lastName
        company {
          id
          name
        }
      }
    }
  }
}
Variables: 
{
  "first": 10
}

​
Query Companies

query GetCompanies($filter: CompanyFilterInput) {
  companies(filter: $filter, first: 100) {
    edges {
      node {
        id
        name
        domain
        industry
        employees
        createdAt
      }
    }
    totalCount
  }
}
Variables: 
{
  "filter": {
    "industry": {
      "eq": "Technology"
    }
  }
}

​
Create Record

mutation CreatePerson($data: PersonCreateInput!) {
  createPerson(data: $data) {
    id
    email
    firstName
    lastName
  }
}
Variables: 
{
  "data": {
    "email": "new@example.com",
    "firstName": "New",
    "lastName": "Contact"
  }
}

​
Update Record

mutation UpdatePerson($id: ID!, $data: PersonUpdateInput!) {
  updatePerson(id: $id, data: $data) {
    id
    email
    firstName
    lastName
    updatedAt
  }
}
Variables: 
{
  "id": "person-uuid-here",
  "data": {
    "firstName": "Updated Name"
  }
}

​
Delete Record

mutation DeletePerson($id: ID!) {
  deletePerson(id: $id) {
    id
  }
}

​
Rate Limits

LimitValue
Requests100 per minute
Batch size60 records per call
Hitting rate limits returns HTTP 429. Implement retry logic with exponential backoff.

​
Error Handling

​
Common Errors

CodeMeaningSolution
401UnauthorizedCheck API key
403ForbiddenCheck permissions
404Not foundVerify record ID
429Rate limitedSlow down, retry
500Server errorRetry or report

​
Response Format

Success: 
{
  "data": {
    "people": {
      "edges": [...]
    }
  }
}
Error: 
{
  "errors": [
    {
      "message": "Unauthorized",
      "extensions": {
        "code": "UNAUTHORIZED"
      }
    }
  ]
}

​
SDK Usage

​
Node.js Example

import { GraphQLClient, gql } from 'graphql-request';

const client = new GraphQLClient('https://<your-internal-domain>/graphql', {
  headers: {
    authorization: `Bearer ${process.env.CONSUELO_API_KEY}`,
  },
});

const query = gql`
  query GetPeople {
    people(first: 10) {
      edges {
        node {
          id
          email
        }
      }
    }
  }
`;

const data = await client.request(query);
console.log(data);

​
Python Example

import requests

url = "https://<your-internal-domain>/graphql"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

query = """
query GetPeople {
  people(first: 10) {
    edges {
      node {
        id
        email
      }
    }
  }
}
"""

response = requests.post(
    url,
    headers=headers,
    json={"query": query}
)

data = response.json()
print(data)

​
Next Steps