Skip to main content

Connecting to Axify programmatically

  • Updated

Axify provides a public REST API that enables you to retrieve projects, teams, and analytics data—including DORA metrics, throughput, lead time, and more—directly from your own scripts, dashboards, or data pipelines.


This guide details the following steps:

  1. Requesting API credentials
  2. Exchanging credentials for an access token
  3. Invoking the Axify API
  4. Accessing the comprehensive API reference (Swagger)

  5. Example requests

Request API credentials

API access is provisioned by the Axify team. To initiate the process, please send an email to help@axify.io including the following information:

- The name of your organization within Axify
- A brief description of your intended use case (e.g., "weekly DORA report in Snowflake")
- The email address of the designated technical contact
 

We will share with you securely a client_id and a client_secret that you'll be able to use to authenticate to our API and use it.
You will receive a response containing:

▎ 🔒 Please treat the client secret with the same confidentiality as a password. Store it securely using a secrets manager (e.g., AWS Secrets Manager, Vault, GitHub Actions secrets) and refrain from committing it to any repository.

 

Obtain an access token


Axify employs the standard OAuth 2.0 Client Credentials grant type. Exchange your client_id and client_secret for a short-lived bearer token, which must be used to authenticate API requests.

Request: https://auth.axify.io

curl -X POST "https://auth.axify.io/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u "<CLIENT_ID>:<CLIENT_SECRET>" \
-d "grant_type=client_credentials"

Response:

{ "access_token": "eyJraWQiOiJ...", "expires_in": 3600, "token_type": "Bearer" }

The access token is valid for one hour (expires_in is specified in seconds). It is recommended to cache the token and request a new one only when it is about to expire, rather than obtaining a new token for every API call.

 

Invoke the Axify API


The production API endpoint is:

https://api.axify.io

Include your access token as a Bearer token in the Authorization header for all requests:

curl "https://api.axify.io/projects" \ -H "Authorization: Bearer <ACCESS_TOKEN>"
 

All responses are returned in JSON format. Standard HTTP status codes are used to indicate the result of each request (e.g., 200 OK, 401 Unauthorized for invalid or expired tokens, 403 Forbidden for insufficient permissions, 404 Not Found, 429 Too Many Requests for rate limiting).

 

API Reference (Swagger)


The complete and continuously updated list of endpoints, parameters, and response schemas is accessible via our Swagger UI: https://api.axify.io/swagger 
 

 

Example Requests


The following examples assume you have already obtained an access token and stored it in the environment variable $TOKEN.
 

List your projects:

curl "https://api.axify.io/projects" \ -H "Authorization: Bearer $TOKEN"
[
  { "id": "9f3c2a1e-...", "name": "Mobile App", "organizationId": "b21e..." },
  { "id": "4d8a51c0-...", "name": "Billing Service", "organizationId": "b21e..." }
]

 

List your teams:

curl "https://api.axify.io/teams" \ -H "Authorization: Bearer $TOKEN"
[
  {
    "id": "team-123",
    "name": "Platform",
    "members": [
      {
        "id": "user-1",
        "name": "Alice Doe",
        "email": "alice@example.com",
        "avatarUrl": "https://..."
      }
    ]
  }
]

 

You may also filter teams by project:

curl "https://api.axify.io/teams?projectId=9f3c2a1e-..." \ -H "Authorization: Bearer $TOKEN"

 

Fetch analytics data:

The /analytics endpoints require three query parameters:

Parameter Description
metrics A comma-separated list of metric IDs (e.g., deployment_frequency,lead_time)
startDate ISO 8601 formatted date (e.g., 2025-04-01)
endDate ISO 8601 formatted date (e.g., 2025-04-30)

Optional filters include projectIds, teamIds, projectGroupIds, and comparisonPeriod.

Aggregate metrics over a specified period:

curl "https://api.axify.io/analytics/aggregate?\
metrics=deployment_frequency,lead_time,change_failure_rate,mean_time_to_recovery&\
startDate=2025-04-01&endDate=2025-04-30&\ teamIds=team-123" \
-H "Authorization: Bearer $TOKEN"
{
  "metrics": {
    "deployment_frequency": {
      "value": 3.4,
      "unit": "per_day",
      "description": "This metric indicates that, on average, there are 3.4 deployments occurring each day. Deployment frequency measures how often new updates, features, or fixes are released to production, reflecting the agility and efficiency of the development and operations teams."
    },
    "lead_time": {
      "value": 26.5,
      "unit": "hours",
      "description": "The lead time here represents the average duration of 26.5 hours from the moment a change is committed in the codebase until it is successfully deployed to production. This metric is crucial for understanding the speed at which new code moves through the development pipeline and reaches end users."
    }
  }
}

 

Time series data suitable for charting:

curl "https://api.axify.io/analytics/timeseries?\
metrics=deployment_frequency&startDate=2025-04-01&endDate=2025-04-30&\
granularity=DAY"\
-H "Authorization: Bearer $TOKEN"

granularity accepts the values DAY, WEEK, or MONTH.

 

Breakdown of metrics by team, project, or contributor:

curl "https://api.axify.io/analytics/breakdown/team?\
metrics=deployment_frequency,lead_time&startDate=2025-04-01&endDate=2025-04-30" \ 
-H "Authorization: Bearer $TOKEN"

Additional breakdown endpoints include /analytics/breakdown/project, /analytics/breakdown/contributor, and /analytics/breakdown/group.

 

Troubleshooting

Symptom Likely Cause / Recommended Resolution
401 Unauthorized response from the token endpoint Incorrect client_id or client_secret, or an incorrect token URL for your environment.
401 Unauthorized response from an API call The access token has expired (valid for 1 hour). Request a new token.
403 Forbidden response from an API call The credentials do not have permission to access the specified organization or resource.
400 Bad Request response from /analytics/* endpoints Missing required parameters (metrics, startDate, endDate) or invalid date format.

 

If you encounter difficulties, please contact help@axify.io with the full request details (URL and headers, excluding the token) and the response status and body.

Related articles