newsletter-to-web/.agents/gitea_api.md at master

Files

JJKiers Agent 81fc63474f docs: Introduce comprehensive agent guidance and Gitea API documentation

This commit adds new documentation to enhance agent readiness within the repository:

- `AGENTS.md`: Provides a high-level overview of the project's purpose, technical stack, key workflows, and repository structure.
- `.agents/gitea_api.md`: Contains detailed instructions and examples for programmatic interaction with the Gitea API, covering operations like fetching and creating issues/pull requests, along with a quick reference of API capabilities.

These additions aim to streamline future autonomous operations by centralizing essential repository knowledge and API usage guidelines. It replaces previous ad-hoc methods for interacting with Gitea.

2026-02-14 19:16:07 +00:00

3.0 KiB

Raw Permalink Blame History

Working with Gitea (API Guidance)

Gitea API Features (Quick Reference)

The Gitea API provides extensive functionality for repository management, user interaction, and project oversight. Key features include:

Repository Management: Create, delete, edit repositories; manage branches, commits, and tags.
Issues & Pull Requests: Create, view, update issues and pull requests; manage comments, labels, and milestones.
User Management: Access user profiles, manage SSH keys, GPG keys, and email addresses.
Organization & Teams: Interact with organizations and their associated teams.
Notifications: Manage user notifications.
Activity Feeds: Retrieve user and repository activity.
Webhooks: Configure webhooks for repository events.

For complete details and all available endpoints, refer to the Gitea Swagger API Documentation.

This repository is hosted on Gitea. Direct API calls are often required for tasks like fetching issues, creating pull requests, etc., as specific tools might not always be available.

Base URL: https://code.kiers.eu API Endpoint Prefix: /api/v1 Repository Path: newsletter-to-web/newsletter-to-web

You can use curl with the FORGEJO_TOKEN (which serves as your Gitea token) for authentication.

Key API Interactions:

Fetch Issues: To get a list of all open issues for this repository:

curl -H "Authorization: Bearer ${FORGEJO_TOKEN}" https://code.kiers.eu/api/v1/repos/newsletter-to-web/newsletter-to-web/issues

Fetch Pull Requests (Merge Requests): Gitea uses "pull requests" in its API, though the UI might call them "merge requests."

curl -H "Authorization: Bearer ${FORGEJO_TOKEN}" https://code.kiers.eu/api/v1/repos/newsletter-to-web/newsletter-to-web/pulls

Create an Issue: You would typically POST to the issues endpoint. The labels field expects an array of label IDs. Example (replace with actual data):

curl -X POST -H "Authorization: Bearer ${FORGEJO_TOKEN}" -H "Content-Type: application/json" -d '{
  "title": "New Issue Title",
  "body": "Description of the new issue.",
  "labels": [1, 2] # Use numerical label IDs
}' https://code.kiers.eu/api/v1/repos/newsletter-to-web/newsletter-to-web/issues

Note: You would need to fetch available labels and their IDs first if you want to apply them.

Create a Pull Request: You would typically POST to the pulls endpoint. Example (replace with actual data and branches):

curl -X POST -H "Authorization: Bearer ${FORGEJO_TOKEN}" -H "Content-Type: application/json" -d '{
  "head": "your-branch-name",
  "base": "main",
  "title": "DRAFT: My New Pull Request",
  "body": "Detailed description of changes in this PR."
}' https://code.kiers.eu/api/v1/repos/newsletter-to-web/newsletter-to-web/pulls

head: The branch with your changes.
base: The branch you want to merge into (e.g., main).

3.0 KiB Raw Permalink Blame History

Working with Gitea (API Guidance)

Gitea API Features (Quick Reference)

Key API Interactions:

3.0 KiB

Raw Permalink Blame History