API Reference

Base URLs

Environment	URL
Development/Staging	`https://api.dev.devgrid.io`
Production	`https://prod.api.devgrid.io`

Authentication

All API requests require authentication using an API key.

Headers

x-api-key: YOUR_API_KEY
Content-Type: application/json

Obtaining an API Key

Log in to DevGrid
Navigate to Settings → API Keys
Click Generate New API Key
Copy and securely store your key

Security Best Practices

Never commit API keys to version control
Store keys in environment variables or secrets management systems
Rotate keys periodically
Use separate keys for different environments (dev, staging, prod)

Endpoints

POST /events

Send one or more events to DevGrid.

URL: POST /events

Request Body:

{
  "events": [
    {
      "type": "string (required)",
      "timestamp": "ISO 8601 datetime (optional)",
      "entityId": "UUID or shortId (optional but recommended)",
      "attributes": {
        // Event-specific attributes
      }
    }
  ]
}

Field Descriptions:

Field	Type	Required	Description
`events`	array	Yes	Array of 1-15 event objects
`events[].type`	string	Yes	Event type identifier (e.g., `"event-deploy"`)
`events[].timestamp`	string	No	ISO 8601 UTC timestamp. Defaults to current time if omitted
`events[].entityId`	string	No*	UUID or shortId of the application/service. *Required for DORA metrics
`events[].attributes`	object	No	Event-specific attributes (see Event Types below)

Constraints:

Maximum 15 events per request
Timestamp must be in ISO 8601 format (e.g., "2025-10-29T18:30:00Z")
entityId must reference an existing entity in your DevGrid account

Response Codes:

Code	Meaning
201	Created - Event(s) successfully received
400	Bad Request - Invalid request format or validation errors
401	Unauthorized - Missing or invalid API key
413	Payload Too Large - More than 15 events in request
500	Internal Server Error - Server-side error

Success Response (201):

{
  "success": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "event-deploy",
      "entityId": "app-entity-id",
      "blueprintId": "04252f20-4000-470a-a1eb-88bf5bb648d2",
      "timestamp": "2025-10-29T18:30:00Z",
      "accountId": "your-account-id",
      "attributes": { ... },
      "createdAt": "2025-10-29T18:30:15Z"
    }
  ],
  "failures": []
}

Partial Success Response (201 with failures):

{
  "success": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "event-deploy",
      ...
    }
  ],
  "failures": [
    {
      "event": {
        "type": "event-deploy",
        "entityId": "invalid-id",
        ...
      },
      "reason": "Entity not found"
    }
  ]
}

Error Response (400, 401, 500):

{
  "message": "Error description"
}

{
  "errors": [
    {
      "type": "field",
      "msg": "Invalid value",
      "path": "events[0].type",
      "location": "body"
    }
  ]
}

Event Types

event-deploy (Deployment Events)

Deployment events are used to calculate Deployment Frequency, Lead Time for Change, and Change Failure Rate.

Type: "event-deploy"

Blueprint ID: 04252f20-4000-470a-a1eb-88bf5bb648d2

Attributes:

All attributes are optional, but certain attributes are required for specific DORA metrics:

Attribute	Type	Required For	Description
`env`	string	Deployment Frequency	Environment name (e.g., "production", "staging", "dev")
`status`	string	Change Failure Rate	Deployment status: `"success"` or `"failed"`
`build_id`	string	-	CI/CD build identifier
`build_commit_sha`	string	Lead Time for Change	Git commit SHA - must match commits in connected repo
`build_url`	string	-	URL to the CI/CD build/pipeline run
`description`	string	-	Human-readable deployment description
`initiator`	string	-	Person or system that triggered the deployment
`change_id`	string	Change Failure Rate	Change management system ticket ID (for linking to incidents)
`change_url`	string	-	URL to the change management ticket
`change_title`	string	-	Change ticket title
`change_author`	string	-	Change ticket author
`change_approver`	string	-	Change ticket approver
`change_window_start`	ISO 8601	-	Scheduled change window start time
`change_window_end`	ISO 8601	-	Scheduled change window end time
`deployment_start_time`	ISO 8601	-	Actual deployment start time

Example Request:

curl -X POST https://prod.api.devgrid.io/events \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "event-deploy",
        "timestamp": "2025-10-29T18:30:00Z",
        "entityId": "app-123",
        "attributes": {
          "env": "production",
          "status": "success",
          "build_id": "build-456",
          "build_commit_sha": "a1b2c3d4e5f6789",
          "build_url": "https://ci.example.com/builds/456",
          "description": "Deploy v2.3.1 to production",
          "initiator": "[email protected]",
          "change_id": "CHG0012345",
          "change_url": "https://servicenow.example.com/change/CHG0012345",
          "change_title": "Production deployment v2.3.1",
          "change_author": "[email protected]",
          "change_approver": "[email protected]",
          "change_window_start": "2025-10-29T18:00:00Z",
          "change_window_end": "2025-10-29T20:00:00Z",
          "deployment_start_time": "2025-10-29T18:25:43Z"
        }
      }
    ]
  }'

Best Practices:

Always include env - This allows you to filter metrics by environment (production only, or include staging)
Always include build_commit_sha - Required for Lead Time for Change calculations
Always include change_id - Required for linking incidents to deployments (Change Failure Rate)
Use consistent environment names - Pick "production" or "prod" and stick with it across all events
Send both successes and failures - Don't just track successful deployments

Additional Event Types

DevGrid supports additional event types for future metrics and analysis:

event-build - CI/CD build events
event-test-run - Test execution events
event-commit - Code commit events (usually synced automatically via version control integration)
event-error - Application error/exception events

Contact DevGrid support for schemas and use cases for these event types.

Rate Limits

Current rate limits (subject to change):

100 requests per minute per API key
1,500 requests per hour per API key

If you exceed rate limits, you'll receive a 429 Too Many Requests response. Implement exponential backoff and retry logic in your integration.

Batch Processing

Recommended Batch Size

Send up to 15 events per request (API maximum)
For large historical data imports, batch events and add delays between requests

Example Batch Request

{
  "events": [
    {
      "type": "event-deploy",
      "timestamp": "2025-10-29T10:00:00Z",
      "entityId": "app-123",
      "attributes": {
        "env": "staging",
        "status": "success"
      }
    },
    {
      "type": "event-deploy",
      "timestamp": "2025-10-29T15:00:00Z",
      "entityId": "app-123",
      "attributes": {
        "env": "production",
        "status": "success"
      }
    },
    {
      "type": "event-deploy",
      "timestamp": "2025-10-29T15:05:00Z",
      "entityId": "app-456",
      "attributes": {
        "env": "production",
        "status": "success"
      }
    }
  ]
}

Error Codes & Troubleshooting

Common Error Codes

Error	Code	Cause	Solution
Unauthorized	401	Missing or invalid API key	Check `x-api-key` header is present and correct
Entity not found	400	Invalid `entityId`	Verify entity exists in DevGrid
Invalid event type	400	Unknown `type` value	Use `"event-deploy"` for deployments
Invalid timestamp	400	Malformed timestamp	Use ISO 8601 format: `"2025-10-29T18:30:00Z"`
Payload too large	413	More than 15 events	Split into multiple requests
Validation error	400	Attributes don't match schema	Check attribute names and types

Validation Rules

Event Type - Must match an existing blueprint shortId (e.g., "event-deploy")
Timestamp - Must be valid ISO 8601 format in UTC
Entity ID - Must reference an existing entity in your account
Attributes - Field names must match blueprint schema (case-sensitive)
Date Attributes - Change window and deployment times must be valid ISO 8601

Data Freshness

Events are ingested immediately upon successful API call
Metrics are calculated daily at UTC midnight
Changes to metrics appear in the dashboard within 24 hours of sending events
Historical data can be backfilled by sending events with past timestamps

Examples

Successful Deployment

curl -X POST https://prod.api.devgrid.io/events \
  -H "x-api-key: $DEVGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "event-deploy",
      "entityId": "my-app",
      "attributes": {
        "env": "production",
        "status": "success",
        "build_commit_sha": "abc123def456"
      }
    }]
  }'

Failed Deployment

curl -X POST https://prod.api.devgrid.io/events \
  -H "x-api-key: $DEVGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "event-deploy",
      "entityId": "my-app",
      "attributes": {
        "env": "production",
        "status": "failed",
        "build_commit_sha": "abc123def456",
        "description": "Deployment failed due to database migration error"
      }
    }]
  }'

Multiple Environments in One Request

curl -X POST https://prod.api.devgrid.io/events \
  -H "x-api-key: $DEVGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "event-deploy",
        "timestamp": "2025-10-29T10:00:00Z",
        "entityId": "my-app",
        "attributes": {
          "env": "staging",
          "status": "success"
        }
      },
      {
        "type": "event-deploy",
        "timestamp": "2025-10-29T14:00:00Z",
        "entityId": "my-app",
        "attributes": {
          "env": "production",
          "status": "success"
        }
      }
    ]
  }'

Testing Your Integration

Test in Development First

Use the development environment to test your integration:

curl -X POST https://api.dev.devgrid.io/events \
  -H "x-api-key: $DEVGRID_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "events": [...] }'

Validate Response

Always check the response for both success and failures arrays:

const response = await fetch('https://prod.api.devgrid.io/events', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.DEVGRID_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ events })
});

const result = await response.json();

if (result.failures && result.failures.length > 0) {
  console.error('Some events failed:', result.failures);
  // Handle failures
}

if (result.success && result.success.length > 0) {
  console.log(`Successfully sent ${result.success.length} events`);
}