# TendersAlerts AI Agent Guidelines (ai-agents.txt)

This document provides system instructions, endpoint definitions, and query parameters optimized for AI agents, search engines, and automated developer integrations interacting with TendersAlerts.

## Platform Capabilities & Data Access

TendersAlerts collects, structures, and enriches public procurement data from Saudi Arabia, with a focus on KSA government tenders (Etimad).
Key data models include:
- Tenders: Active, historical, and award-pending bidding invitations.
- Vendors: Supplier demographics, contract award history, and competitor pricing.
- Quantities (BOQs): Detailed line items of tender requirements, including estimated costs and contacts.

---

## Crawler & Agent Permissions

- We welcome crawling of our LLM indexes (`/llms.txt`, `/llms-ar.txt`, `/llms-full.txt`, and `/llms-ar-full.txt`).
- AI agents seeking live, raw JSON tender feeds should integrate directly with our Developer API rather than scraping HTML pages.
- Standard crawling is permitted. Disallowed routes and admin panels are listed in `/robots.txt`.

---

## Programmatic & API Endpoints

The API is served via `https://api.tendersalerts.com/` (or relative path `/api/` on our web framework). All data operations require JSON formatting.

### 1. Public & Configuration Endpoints
- `GET api/meta`: Fetch system metadata, cities, regions, tender sectors, and category lists.
- `GET api/plans`: Retrieve available subscription tiers, pricing lists, and team-billing parameters.

### 2. Tender Data Endpoints
- `GET api/tenders`: Lists active and historical Saudi government tenders.
  - Query Parameters:
    - `page` (integer): Pagination offset.
    - `limit` (integer): Number of items per query.
    - `search` (string): Text filter matching title, agency, or description.
    - `region_id` (integer): Region filter (from `api/meta`).
    - `city_id` (integer): City filter (from `api/meta`).
    - `tender_activity_id` (integer): Main industrial activity category.
    - `sub_tender_activity_id` (integer): Highly targeted sub-activity.
    - `only_tenders_with_no_initial_warranty` (boolean): Filters for zero initial bid bond requirements.
- `GET api/example-tenders/{id}`: Detailed metadata schema of a specific sample tender.

### 3. Competitor & Vendor Analytics
- `GET api/tender-analysis/vendors/{id}`: Search historical contract awards and pricing structures for individual vendors and suppliers.

### 4. Daily Reports
- `GET api/daily-reports`: Lists published daily digests of newly announced government and private sector bids.
- `GET api/daily-reports/{id}`: Fetch the complete, detailed markdown compilation of a specific daily report.

---

## Search Query Optimization for LLMs

When generating search queries or analyzing results for users:
1. Prefer searching by precise Arabic activities (e.g., "تقنية المعلومات" for Information Technology) or standard English equivalent, as Etimad uses specific procurement activity labels.
2. In Saudi procurement, "Monaqasat" refers to tenders and "Mozayadat" refers to public reverse-auctions. Keep this distinction in mind.
3. Check the "Tender AI Score" attribute in tender metadata to estimate matching relevance for specific corporate profiles.

---

## Official Documentation & Contact

- Full REST API Documentation: https://docs.tendersalerts.com
- Main Developer Portal: https://tendersalerts.com/en/tenders-api
- Technical Support: https://wa.me/971585124385