tendril/docs/GITEA/Gitea-API-Reference.md

Gitea API Reference for LLMs

Purpose: API differences and considerations when working with Gitea programmatically.

Reference: Gitea API Documentation

---

Overview

Gitea provides a REST API that is similar to GitHub's API but not identical. The API allows programmatic access to repositories, issues, pull requests, and more.

Base URL: https://your-gitea-instance.com/api/v1

---

Authentication

Personal Access Token

Creating a token:

1. Log in to Gitea
2. Go to Settings → Applications → Generate New Token
3. Set name and permissions
4. Copy token

Using token:

curl -H "Authorization: token YOUR_TOKEN" \
  https://git.parkingmeter.info/api/v1/user

In code:

let client = reqwest::Client::new();
let response = client
    .get("https://git.parkingmeter.info/api/v1/user")
    .header("Authorization", format!("token {}", token))
    .send()
    .await?;

---

Common Endpoints

User Information

Get authenticated user:

GET /api/v1/user

Get user by username:

GET /api/v1/users/{username}

Repositories

List repositories:

GET /api/v1/user/repos
GET /api/v1/users/{username}/repos
GET /api/v1/orgs/{org}/repos

Get repository:

GET /api/v1/repos/{owner}/{repo}

Create repository:

POST /api/v1/user/repos

Issues

List issues:

GET /api/v1/repos/{owner}/{repo}/issues

Get issue:

GET /api/v1/repos/{owner}/{repo}/issues/{index}

Create issue:

POST /api/v1/repos/{owner}/{repo}/issues

Pull Requests

List pull requests:

GET /api/v1/repos/{owner}/{repo}/pulls

Get pull request:

GET /api/v1/repos/{owner}/{repo}/pulls/{index}

Create pull request:

POST /api/v1/repos/{owner}/{repo}/pulls

---

Differences from GitHub API

1. Base URL

• GitHub: https://api.github.com
• Gitea: https://your-instance.com/api/v1

2. Issue/PR Numbers

• GitHub: Uses sequential numbers across repository
• Gitea: Uses index (similar, but may differ in some cases)

3. Some Endpoints

• Gitea may have different endpoints for some operations
• Check Gitea API documentation for specific endpoints
• Most common operations are similar

4. Webhooks

• Gitea webhooks are compatible with GitHub format
• Same payload structure
• Same event types (push, pull_request, etc.)

---

For LLMs: API Usage Guidelines

When Documenting API Usage

Reference Gitea API:

## API Integration

This project uses the **Gitea API** for programmatic access.

**Base URL**: `https://git.parkingmeter.info/api/v1`

**Authentication**: Personal Access Token

**Example**:
```bash
curl -H "Authorization: token YOUR_TOKEN" \
  https://git.parkingmeter.info/api/v1/user/repos

### When Creating API Clients

**Use Gitea base URL**:
```rust
const GITEA_BASE_URL: &str = "https://git.parkingmeter.info/api/v1";

Use Gitea authentication:

let client = reqwest::Client::new();
let response = client
    .get(&format!("{}/user", GITEA_BASE_URL))
    .header("Authorization", format!("token {}", token))
    .send()
    .await?;

When Referencing Documentation

Link to Gitea API docs:

For complete API documentation, see:
https://docs.gitea.com/api/

---

Common Use Cases

1. Listing Repositories

curl -H "Authorization: token YOUR_TOKEN" \
  https://git.parkingmeter.info/api/v1/user/repos

2. Creating an Issue

curl -X POST \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"New Issue","body":"Issue description"}' \
  https://git.parkingmeter.info/api/v1/repos/owner/repo/issues

3. Creating a Pull Request

curl -X POST \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"PR Title","head":"feature-branch","base":"main"}' \
  https://git.parkingmeter.info/api/v1/repos/owner/repo/pulls

---

MCP Server Integration

Tendril uses the Gitea MCP server for integration with Zed IDE. The MCP server provides:

• Repository management
• Issue management
• Pull request management
• File operations
• And more

Reference: See src/mcp_server_gitea.rs for implementation details.

---

References

• Gitea API Docs: https://docs.gitea.com/api/
• API Overview: https://docs.gitea.com/api/overview/
• Authentication: https://docs.gitea.com/api/authentication/

---

Location: docs/GITEA/Gitea-API-Reference.md
Last Updated: 2025-01-27