Name: Agent Yield Lab API: Endpoint Preflight and Flight Scoring
Brand: ayl
SKU: api-ayl-agent-yield-lab
Availability: InStock
Author: API Market

# Agent Yield Lab Utility API

## Overview

Agent Yield Lab gives AI agents and automation pipelines three focused utilities: check that an HTTPS endpoint is up before you call or pay for it, verify a batch of search result URLs, and rank award-flight options against a traveller's preferences. Every endpoint takes bounded inputs and returns deterministic, structured JSON, so the same input always gives the same result.

## Features

- **Endpoint preflight:** reachability, HTTP status, latency, redirects and detected x402 payment metadata for any public HTTPS URL, with a `pass`, `warning` or `fail` verdict.
- **Search result verification:** checks up to 10 URLs per request for reachability, final URL, redirect chain, page title match, freshness headers and warnings.
- **Award flight scoring:** ranks up to 50 award-flight options by miles, cash fees, cabin, loyalty programme, dates and directness, and explains every score.
- **Deterministic output:** no model calls, no randomness. Results are repeatable and easy to test.

## Use Cases

- **Agent tool screening:** preflight a paid or x402 API before an agent spends money on it.
- **Research pipelines:** drop broken, redirected or mismatched sources after a web search step.
- **Award travel tools:** turn raw award availability from any source into a ranked shortlist with reasons.
- **Monitoring:** run scheduled preflight checks on the services your workflow depends on.

## API Documentation

### Base URL

```
https://prod.api.market/api/v1/ayl/agent-yield-lab
```

### Authentication

Send your API.market key in the `x-api-market-key` header with every request.

### Endpoints

#### 1. Endpoint Preflight

`GET /v1/preflight`

Checks a public HTTPS endpoint and reports reachability, status, latency, redirects and x402 payment details.

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| target | query | Public HTTPS URL to check | string (uri) | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/ayl/agent-yield-lab/v1/preflight?target=https%3A%2F%2Fexample.com" \
  -H "accept: application/json" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response:**

```json
{
  "target": "https://example.com/",
  "checkedAt": "2026-10-01T21:27:03.729Z",
  "reachable": true,
  "status": 200,
  "latencyMs": 11,
  "https": true,
  "redirectLocation": null,
  "x402": {
    "advertised": false,
    "paymentRequired": false,
    "headerNames": [],
    "protocolVersion": null,
    "schemes": [],
    "networks": [],
    "assets": [],
    "payToAddresses": [],
    "quotedPriceUsd": null
  },
  "verdict": "warning",
  "warnings": [
    "no x402 payment requirement detected"
  ]
}
```

#### 2. Search Result Verifier

`POST /v1/search-verify`

Verifies a list of URLs, for example the results of a web search, and returns a verdict for each one.

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| results | body | List of URLs to verify | array | Yes | - | 10 items |
| results[].url | body | URL to verify | string (uri) | Yes | - | - |
| results[].expectedTitle | body | Title you expect the page to have, used for `titleSimilarity` | string | No | - | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/ayl/agent-yield-lab/v1/search-verify" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -d '{"results":[{"url":"https://example.com","expectedTitle":"Example Domain"}]}'
```

**Example Response:**

```json
{
  "checkedAt": "2026-10-01T21:27:18.870Z",
  "requested": 1,
  "processed": 1,
  "summary": {
    "pass": 1,
    "warning": 0,
    "fail": 0
  },
  "results": [
    {
      "inputUrl": "https://example.com",
      "finalUrl": "https://example.com/",
      "reachable": true,
      "httpStatus": 206,
      "redirectCount": 0,
      "redirectChain": [],
      "latencyMs": 9,
      "contentType": "text/html; charset=utf-8",
      "title": "Example Domain",
      "expectedTitle": "Example Domain",
      "titleSimilarity": 1,
      "canonicalUrl": null,
      "freshnessEvidence": {
        "lastModified": "Mon, 28 Sep 2026 16:19:32 GMT",
        "lastModifiedAgeDays": 3.2,
        "etag": "\"6aba9394-2c9\"",
        "dateHeader": "Thu, 01 Oct 2026 21:27:18 GMT"
      },
      "verdict": "pass",
      "warnings": []
    }
  ]
}
```

#### 3. Award Flight Result Scorer

`POST /v1/award-flight-score`

Scores and ranks award-flight options you supply against the traveller's preferences. It does not search airline inventory.

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| results | body | Award-flight options to score | array | Yes | - | 50 items |
| results[].id | body | Your identifier for the option | string | No | - | - |
| results[].date | body | Departure date (YYYY-MM-DD) | string | Yes | - | - |
| results[].origin | body | Origin airport code | string | Yes | - | - |
| results[].destination | body | Destination airport code | string | Yes | - | - |
| results[].cabin | body | Cabin, for example `economy` or `business` | string | Yes | - | - |
| results[].seats | body | Seats available | integer | Yes | - | - |
| results[].milesPerPassenger | body | Miles required per passenger | number | Yes | - | - |
| results[].cashFeesUsdPerPassenger | body | Taxes and fees per passenger in USD | number | No | - | - |
| results[].direct | body | Whether the itinerary is direct | boolean | No | - | - |
| results[].program | body | Loyalty programme code | string | No | - | - |
| preferences.passengers | body | Number of passengers | integer | Yes | - | 9 |
| preferences.maxMilesPerPassenger | body | Mileage budget per passenger | number | No | - | - |
| preferences.maxCashFeesUsdPerPassenger | body | Cash fee budget per passenger in USD | number | No | - | - |
| preferences.preferDirect | body | Prefer direct itineraries | boolean | No | - | - |
| preferences.preferredCabins | body | Preferred cabins | array | No | - | - |
| preferences.preferredPrograms | body | Preferred loyalty programmes | array | No | - | - |
| preferences.earliestDate | body | Earliest acceptable date (YYYY-MM-DD) | string | No | - | - |
| preferences.latestDate | body | Latest acceptable date (YYYY-MM-DD) | string | No | - | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/ayl/agent-yield-lab/v1/award-flight-score" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -d '{"results":[{"id":"opt-1","date":"2026-11-14","origin":"JFK","destination":"LHR","cabin":"business","seats":2,"milesPerPassenger":57500,"cashFeesUsdPerPassenger":5.6,"direct":true,"program":"AA"},{"id":"opt-2","date":"2026-11-15","origin":"JFK","destination":"LHR","cabin":"business","seats":4,"milesPerPassenger":88000,"cashFeesUsdPerPassenger":420,"direct":true,"program":"BA"}],"preferences":{"passengers":2,"maxMilesPerPassenger":90000,"preferDirect":true,"preferredCabins":["business"],"preferredPrograms":["AA"]}}'
```

**Example Response:**

```json
{
  "scoredAt": "2026-10-01T21:27:04.766Z",
  "requested": 2,
  "eligible": 2,
  "rejected": 0,
  "best": [
    {
      "id": "opt-1",
      "date": "2026-11-14",
      "origin": "JFK",
      "destination": "LHR",
      "cabin": "business",
      "seats": 2,
      "milesPerPassenger": 57500,
      "cashFeesUsdPerPassenger": 5.6,
      "direct": true,
      "program": "AA",
      "score": 95,
      "rank": 1,
      "eligible": true,
      "paretoOptimal": true,
      "totalMiles": 115000,
      "totalCashFeesUsd": 11.2,
      "reasons": [
        "enough seats and date is within requested window",
        "preferred cabin",
        "within mileage budget",
        "direct itinerary",
        "preferred loyalty programme",
        "strong mileage efficiency within this batch",
        "Pareto-efficient on miles / fees / directness"
      ],
      "warnings": [],
      "rejectionReasons": []
    },
    {
      "id": "opt-2",
      "date": "2026-11-15",
      "origin": "JFK",
      "destination": "LHR",
      "cabin": "business",
      "seats": 4,
      "milesPerPassenger": 88000,
      "cashFeesUsdPerPassenger": 420,
      "direct": true,
      "program": "BA",
      "score": 80,
      "rank": 2,
      "eligible": true,
      "paretoOptimal": false,
      "totalMiles": 176000,
      "totalCashFeesUsd": 840,
      "reasons": [
        "enough seats and date is within requested window",
        "preferred cabin",
        "within mileage budget",
        "direct itinerary"
      ],
      "warnings": [
        "programme is not in preferred list"
      ],
      "rejectionReasons": []
    }
  ],
  "ranked": [
    {
      "id": "opt-1",
      "date": "2026-11-14",
      "origin": "JFK",
      "destination": "LHR",
      "cabin": "business",
      "seats": 2,
      "milesPerPassenger": 57500,
      "cashFeesUsdPerPassenger": 5.6,
      "direct": true,
      "program": "AA",
      "score": 95,
      "rank": 1,
      "eligible": true,
      "paretoOptimal": true,
      "totalMiles": 115000,
      "totalCashFeesUsd": 11.2,
      "reasons": [
        "enough seats and date is within requested window",
        "preferred cabin",
        "within mileage budget",
        "direct itinerary",
        "preferred loyalty programme",
        "strong mileage efficiency within this batch",
        "Pareto-efficient on miles / fees / directness"
      ],
      "warnings": [],
      "rejectionReasons": []
    },
    {
      "id": "opt-2",
      "date": "2026-11-15",
      "origin": "JFK",
      "destination": "LHR",
      "cabin": "business",
      "seats": 4,
      "milesPerPassenger": 88000,
      "cashFeesUsdPerPassenger": 420,
      "direct": true,
      "program": "BA",
      "score": 80,
      "rank": 2,
      "eligible": true,
      "paretoOptimal": false,
      "totalMiles": 176000,
      "totalCashFeesUsd": 840,
      "reasons": [
        "enough seats and date is within requested window",
        "preferred cabin",
        "within mileage budget",
        "direct itinerary"
      ],
      "warnings": [
        "programme is not in preferred list"
      ],
      "rejectionReasons": []
    }
  ],
  "rejectedResults": [],
  "methodology": {
    "maxScore": 100,
    "scoring": [
      "20 points for minimum eligibility (enough seats and date window)",
      "up to 20 for preferred cabin",
      "up to 20 for mileage budget fit",
      "up to 10 for cash-fee budget fit",
      "up to 15 for direct-flight preference",
      "up to 5 for preferred loyalty programme",
      "up to 10 for relative mileage efficiency within the submitted batch"
    ],
    "hardRejects": [
      "insufficient seats",
      "outside requested date window"
    ],
    "paretoDimensions": [
      "milesPerPassenger",
      "cashFeesUsdPerPassenger when supplied",
      "directness when preferred"
    ]
  }
}
```

## Status Codes

| Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid input, for example `{"error":"results must contain between 1 and 10 items"}` |
| 401 | Missing or invalid API.market key |
| 429 | Plan quota exceeded |
| 500 | Internal server error |

## Rate Limits

- **Free:** 50 API units, 7-day trial
- **Pro ($4.99/month):** 1,000 API units per month
- Up to 10 requests per second on both plans

Each successful request uses 1 API unit.

## FAQ

**Does the award flight scorer search for flights?**
No. It only scores the options you send. Pair it with your own availability source.

**What is x402?**
x402 is a protocol for paying for API calls over HTTP 402 responses. The preflight endpoint reports whether a target advertises x402 payment details and what it asks for.

**How many URLs can I verify at once?**
Up to 10 per request to `/v1/search-verify`.

**Are the results deterministic?**
Yes. The same input returns the same verdicts and scores, apart from live data such as latency and status.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Preflight any HTTPS endpoint, verify search result URLs and rank award-flight options with one API. Deterministic JSON for AI agents and automation.