API Reference

Overview

gityar provides a comprehensive REST API that allows you to automate tasks, integrate with other tools, and build custom applications.

Authentication

Basic Authentication

curl -u "username:password" http://localhost:3000/api/v1/user

Access Token (Recommended)

Generate a token in Settings → Applications → Generate New Token

curl -H "Authorization: token YOUR_TOKEN" http://localhost:3000/api/v1/user

Query Parameter

curl http://localhost:3000/api/v1/user?token=YOUR_TOKEN

Base URL

http://localhost:3000/api/v1

Or your configured domain:

https://gityar.example.com/api/v1

API Endpoints

User

Get authenticated user

GET /api/v1/user

Response:

{
  "id": 1,
  "login": "username",
  "full_name": "Full Name",
  "email": "user@example.com",
  "avatar_url": "http://localhost:3000/user/avatar/username",
  "created_at": "2024-01-01T00:00:00Z"
}

Get user by username

GET /api/v1/users/:username

Repositories

List your repositories

GET /api/v1/user/repos

List user repositories

GET /api/v1/users/:username/repos

Get repository

GET /api/v1/repos/:owner/:repo

Create repository

POST /api/v1/user/repos

{
  "name": "my-repo",
  "description": "My repository",
  "private": false,
  "auto_init": true
}

Delete repository

DELETE /api/v1/repos/:owner/:repo

Issues

List issues

GET /api/v1/repos/:owner/:repo/issues
GET /api/v1/issues?filter=all

Create issue

POST /api/v1/repos/:owner/:repo/issues

{
  "title": "Bug: Something broken",
  "body": "Detailed description",
  "labels": [1, 2],
  "assignee": "username"
}

Get issue

GET /api/v1/repos/:owner/:repo/issues/:index

Update issue

PATCH /api/v1/repos/:owner/:repo/issues/:index

{
  "title": "Updated title",
  "state": "closed"
}

Pull Requests

List pull requests

GET /api/v1/repos/:owner/:repo/pulls

Create pull request

POST /api/v1/repos/:owner/:repo/pulls

{
  "title": "Add new feature",
  "body": "Description of changes",
  "head": "feature-branch",
  "base": "main"
}

Merge pull request

POST /api/v1/repos/:owner/:repo/pulls/:index/merge

Organizations

List your organizations

GET /api/v1/user/orgs

Get organization

GET /api/v1/orgs/:org

Create organization

POST /api/v1/orgs

{
  "username": "my-org",
  "full_name": "My Organization"
}

Webhooks

List repository webhooks

GET /api/v1/repos/:owner/:repo/hooks

Create webhook

POST /api/v1/repos/:owner/:repo/hooks

{
  "type": "gitea",
  "config": {
    "url": "https://example.com/webhook",
    "content_type": "json",
    "secret": "your-secret"
  },
  "events": ["push", "issues"],
  "active": true
}

Pagination

All list endpoints support pagination:

GET /api/v1/user/repos?page=2&limit=20

Response headers include:

• X-Page: Current page number
• X-PerPage: Items per page
• X-Total-Count: Total items

Rate Limiting

API requests are rate-limited to prevent abuse.

Headers:

• X-RateLimit-Limit: Maximum requests per hour
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Time when limit resets

Error Responses

400 Bad Request

{
  "message": "Invalid request",
  "url": "http://localhost:3000/api/v1"
}

401 Unauthorized

{
  "message": "Unauthorized"
}

404 Not Found

{
  "message": "Repository not found",
  "url": "http://localhost:3000/api/v1"
}

422 Unprocessable Entity

{
  "message": "Validation failed",
  "errors": [
    {
      "resource": "Repository",
      "field": "name",
      "code": "invalid"
    }
  ]
}

Code Examples

Python

import requests

# Authentication
headers = {
    'Authorization': 'token YOUR_TOKEN'
}

# List repositories
response = requests.get(
    'http://localhost:3000/api/v1/user/repos',
    headers=headers
)

repos = response.json()
for repo in repos:
    print(repo['full_name'])

# Create issue
response = requests.post(
    'http://localhost:3000/api/v1/repos/owner/repo/issues',
    headers=headers,
    json={
        'title': 'Bug report',
        'body': 'Detailed description'
    }
)

JavaScript (Node.js)

const axios = require('axios');

const client = axios.create({
  baseURL: 'http://localhost:3000/api/v1',
  headers: {
    'Authorization': 'token YOUR_TOKEN'
  }
});

// List repositories
async function listRepos() {
  const response = await client.get('/user/repos');
  return response.data;
}

// Create issue
async function createIssue(owner, repo, issue) {
  const response = await client.post(
    `/repos/${owner}/${repo}/issues`,
    issue
  );
  return response.data;
}

cURL

# Get user info
curl -H "Authorization: token YOUR_TOKEN" \
  http://localhost:3000/api/v1/user

# Create repository
curl -X POST \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-repo","description":"My repository"}' \
  http://localhost:3000/api/v1/user/repos

Next Steps

• Explore Webhooks
• Learn about Git LFS
• Read about Migration