# Upwork Services

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/upwork/services` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/upwork-services |

## Description

Upwork Services API: browse Project Catalog listings by category slug or URL. Returns prices, product IDs and pagination via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/upwork/services' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Mobile Apps category (page 1)

```json
{
  "name": "Mobile Apps",
  "results": [
    {
      "title": "Mobile App Development | Android Apps | iOS Apps | Flutter Application DevMobile App Development | Android Apps | iOS Apps | Flutter Application Dev",
      "rating": null,
      "currency": "USD",
      "image_url": "https://res.cloudinary.com/upwork-cloud/image/upload/c_scale,w_400/v1765222199/catalog/1403673770703212544/lxul06rynupzvk1jkz8s.jpg",
      "price_from": 399,
      "product_id": "1403673770703212544",
      "listing_url": "https://www.upwork.com/services/product/development-it-mobile-app-developer-android-ios-flutter-application-hybrid-apps-1403673770703212544"
    },
    {
      "title": "Mobile App Developer, Android, iOS App Development in Flutter, App DesignerMobile App Developer, Android, iOS App Development in Flutter, App Designer",
      "rating": null,
      "currency": "USD",
      "image_url": "https://res.cloudinary.com/upwork-cloud/image/upload/c_scale,w_400/v1750666442/catalog/1784861153261067753/p9oduz9tvcfgpomnqqow.jpg",
      "price_from": 499,
      "product_id": "1784861153261067753",
      "listing_url": "https://www.upwork.com/services/product/development-it-android-ios-mobile-app-development-using-flutter-expert-ai-app-developer-1784861153261067753"
    }
  ],
  "category": "mobile-apps",
  "pagination": {
    "next": null,
    "page": 1,
    "per_page": 24,
    "total_pages": null,
    "total_results": null
  }
}
```

## Documentation

## Overview
The **Upwork Services API** returns Project Catalog listings from [Upwork](https://www.upwork.com) category pages (`/services/{category-slug}`). Pass a **category slug** or **full URL** and receive catalog cards with titles, prices, product IDs, and pagination metadata.

Piloterr uses **browser rendering** to load Nuxt catalog pages and extract `.project-tile` cards.

Use each result's `listing_url` with **Upwork Services Info** for packages, seller info, and media.

## Quickstart
```
GET https://api.piloterr.com/v2/upwork/services?query=mobile-apps
```

Via POST:
```
POST https://api.piloterr.com/v2/upwork/services
Content-Type: application/json

{"query": "mobile-apps", "return_page_source": false}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Category slug or `/services/{slug}` URL |
| `return_page_source` | boolean | no | Raw HTML as `{"result": "..."}` (default: `false`) |

## Response: each listing (`results[]`)
| Field | Type | Description |
|---|---|---|
| `product_id` | string | Catalog product ID |
| `title` | string | Listing title |
| `listing_url` | string | Product URL |
| `price_from` | number \| null | Starting price |
| `currency` | string \| null | ISO 4217 code |
| `rating` | number \| null | Star rating |
| `image_url` | string \| null | Thumbnail URL |

## Response: pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Listings on this page |
| `total_results` | integer \| null | Total listings (often null) |
| `total_pages` | integer \| null | Total pages (often null) |
| `next` | string \| null | Next page URL |

## Upwork API workflow
1. **Upwork Services**: discover catalog listings by category (this endpoint)
2. **Upwork Services Info**: fetch full product JSON from any `listing_url`
3. **Upwork Freelancer**: enrich the seller profile from `seller.url`

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Category page not parseable |
| `500` | Rendering or parsing error |

## Notes
- Rejects `/services/product/...` URLs: use **Upwork Services Info** instead.
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **Catalog discovery**: harvest product IDs by category
- **Price benchmarking**: compare starting prices across listings
- **Marketplace monitoring**: track new catalog offerings