API Reference

Welcome to the Gitar External API reference. This API allows you to run automated agents on your repositories. This documentation is automatically generated from our OpenAPI specification.

Repository Formats

When specifying a repository, you can use any of the following formats:

• GitHub repository: "owner/repo" (e.g., "myorg/myrepo")
• GitLab repository: "group/project" (e.g., "mygroup/myproject")
• Full repository URL: "https://github.com/owner/repo"
• Repository name: As configured in your Gitar organization

Base URL

All API requests should be made to:

https://api.gitar.ai/v1/external

Authentication

All endpoints require authentication using a Bearer token. Include your API token in the Authorization header:

Authorization: Bearer your_api_token_here

Creating an API Token

To create an API token for accessing the Gitar External API:

1. Navigate to your Gitar organization settings
2. Click on "Create API Token"
3. Fill out the token creation form:
   • Alias (optional): A descriptive name for your token (e.g., "CI/CD Pipeline")
   • Duration: Set the token expiration (default is 30 days)
   • Scopes: Select the permissions for this token. At least one scope must be selected.

Available Scopes

• Administrator: Full access to all resources - provides complete access to your organization
• Read Only: Read access to all resources - allows viewing data without making changes

Choose the scope that provides the minimum permissions needed for your use case to follow security best practices.

Available Endpoints

You can browse the available API endpoints in the sidebar navigation.

Rate Limiting

API requests are rate limited. Please refer to the response headers for current rate limit information.

Error Handling

The API uses standard HTTP response codes to indicate the success or failure of requests:

• 200 OK - The request was successful
• 201 Created - A resource was successfully created
• 400 Bad Request - The request was invalid
• 401 Unauthorized - Authentication failed
• 403 Forbidden - You don't have permission to access this resource
• 404 Not Found - The requested resource was not found
• 500 Internal Server Error - An error occurred on the server

Scopes

API tokens can be configured with different scopes to control access to various endpoints. Agent execution requires the TracksWrite scope.