# Recipes (/docs/recipes)

A recipe is a script we have already written for a common job. You call it by name with
your API key, pass a few inputs, and get the answer back as JSON. You never write a script
or read the library first.

Every recipe is also published as plain source in
[github.com/bowmark-ai/web/recipes](https://github.com/bowmark-ai/web/tree/main/recipes).
Read it to see exactly what runs, or copy it and change it for your own job.

## Call a recipe

```sh
curl -sS -X POST https://api.bowmark.ai/v1/recipes/find-booking-links \
  -H "Authorization: Bearer $BOWMARK_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Caleb Peffer","email":"caleb@firecrawl.dev"}'
```

The answer is the same envelope [`POST /v1/run`](/docs/api#the-two-calls) returns. Read
`result`. A recipe run is billed exactly like any other run.

|                        |                                                                        |
| ---------------------- | ---------------------------------------------------------------------- |
| `GET /v1/recipes`      | Lists every recipe with its inputs and an example body. No key needed. |
| `GET /v1/recipes/:id`  | One recipe, including its full script. No key needed.                  |
| `POST /v1/recipes/:id` | Runs it. The body is the recipe's inputs as JSON. Needs your key.      |

A body with a missing or wrong input is refused with a `400` that lists every problem at
once, before anything runs or is charged.

## find-booking-links

Finds the Calendly, Cal.com, SavvyCal or HubSpot link a person publishes, reads its events
and whether it is open, and tells you how sure we are the calendar is theirs.

Only `name` is required. Every other input is one more place to look for a link the
person posted themselves, which is what turns a guess into a confirmed answer.

| Input     | Type             | What it adds                                                                                          |
| --------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
| `name`    | string, required | Their full name, first and last                                                                       |
| `email`   | string           | A work email fills in `domain` and `company`. Gmail and the like are ignored.                         |
| `company` | string           | Their company's name. Tries calendar names like `caleb-firecrawl`.                                    |
| `domain`  | string           | Their company's website. Its home, about, team and contact pages are read.                            |
| `x`       | string           | Their X handle or profile URL. The bio and the website it lists are read.                             |
| `github`  | string           | Their GitHub handle. The profile README and the site it lists are read.                               |
| `urls`    | string\[]        | Any other page of theirs: a personal site, a speaker bio, a blog post                                 |
| `archive` | boolean          | Also read old saved copies of their company's pages, for a link since removed. Adds 10 to 30 seconds. |

What comes back in `result`:

```json
{
  "name": "Christopher Powroznik",
  "best": {
    "url": "https://calendly.com/christopher-bowmark-ai/bowmark-discovery",
    "platform": "calendly",
    "confidence": "confirmed",
    "evidence": "written on https://bowmark.ai/",
    "owner": "Christopher Powroznik",
    "events": [{ "name": "Bowmark Discovery", "url": "https://calendly.com/christopher-bowmark-ai/bowmark-discovery", "minutes": null }],
    "bookable": "open",
    "qualifyingQuestions": []
  },
  "links": [],
  "checked": 18,
  "warnings": []
}
```

Every link carries a `confidence`:

| `confidence` | Means                                                                               |
| ------------ | ----------------------------------------------------------------------------------- |
| `confirmed`  | Written on a page of theirs: their company site, X bio, GitHub, or a URL you passed |
| `likely`     | Found by name, and the booking page or its URL names their company                  |
| `unverified` | Found by name alone. Someone else with the same name could own it.                  |

`best` is the strongest `confirmed` or `likely` link. It is `null` rather than a guess, so
you never email a stranger's calendar.

## Run the source yourself

Each recipe file is a plain `POST /v1/run` script that reads its inputs from a global named
`input`. Put one line in front of it and send it to `run`:

```sh
SCRIPT="const input = {\"name\":\"Caleb Peffer\",\"company\":\"firecrawl\"};
$(curl -sS https://raw.githubusercontent.com/bowmark-ai/web/main/recipes/find-booking-links.js)"
curl -sS -X POST https://api.bowmark.ai/v1/run \
  -H "Authorization: Bearer $BOWMARK_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --arg s "$SCRIPT" '{script: $s}')"
```

From there it is your script. Every `bowmark.*` function it calls is documented by
[`GET /v1/library`](/docs/api#the-two-calls).