# API Reference

Complete API reference for sending events to DevGrid to calculate DORA metrics.

## 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

1. Log in to DevGrid
2. Navigate to **Settings** → **API Keys**
3. Click **Generate New API Key**
4. 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:**

```json
{
  "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):**

```json
{
  "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):**

```json
{
  "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):**

```json
{
  "message": "Error description"
}
```

or

```json
{
  "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:**

```bash
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": "john.doe@example.com",
          "change_id": "CHG0012345",
          "change_url": "https://servicenow.example.com/change/CHG0012345",
          "change_title": "Production deployment v2.3.1",
          "change_author": "john.doe@example.com",
          "change_approver": "jane.smith@example.com",
          "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:**

1. **Always include `env`** - This allows you to filter metrics by environment (production only, or include staging)
2. **Always include `build_commit_sha`** - Required for Lead Time for Change calculations
3. **Always include `change_id`** - Required for linking incidents to deployments (Change Failure Rate)
4. **Use consistent environment names** - Pick "production" or "prod" and stick with it across all events
5. **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

```json
{
  "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

1. **Event Type** - Must match an existing blueprint shortId (e.g., `"event-deploy"`)
2. **Timestamp** - Must be valid ISO 8601 format in UTC
3. **Entity ID** - Must reference an existing entity in your account
4. **Attributes** - Field names must match blueprint schema (case-sensitive)
5. **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

```bash
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

```bash
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

```bash
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:

```bash
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:

```javascript
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`);
}
```

<br />

<br />