> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enricho.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Search gigs

> Open freelance gigs to apply for, at 5 credits per new gig. No free preview.

Open freelance gigs for freelancers to apply to, newest first. `query` (the skill or kind of work) is required; `budget_type`, the hourly and fixed budget ranges, `experience_level`, `project_length`, `hours_per_week`, `client_hires` and `client_country` narrow the search.

There is no free preview: every call returns full gigs at 5 credits each. Start with a small `limit` (default 10).

## Search and continuation

```bash theme={null}
curl -X POST 'https://api.enricho.co/api/directory/gigs/search' \
  -H 'Authorization: Bearer enr_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"query":"shopify developer","budget_type":"fixed","fixed_budget_min":500,"client_hires":["1_to_9","10_plus"],"limit":5}'
```

Each new gig costs 5 credits; gigs you already bought are free and counted in `already_purchased`. When `has_more` is true, send the same body with `cursor` set to `next_cursor`. A search's results are kept for a few hours, so pages and repeats are consistent; if a cursor has expired, start again without it.

Each gig has `apply_url`, the posting on the freelance marketplace, where you apply with your own freelancer account.


## OpenAPI

````yaml api-reference/openapi.json POST /api/directory/gigs/search
openapi: 3.1.0
info:
  title: Enricho Public REST API
  version: 1.0.0
  description: >-
    Public directory search and billing APIs. Full search costs 5 credits per
    new record; previews and usage calls use no credits. Request and response
    contracts reflect the current public gateway and service handlers.
servers:
  - url: https://api.enricho.co
security:
  - apiKey: []
  - headerKey: []
tags:
  - name: Directory
  - name: Billing
paths:
  /api/directory/gigs/search:
    post:
      tags:
        - Directory
      summary: Search gigs
      description: >-
        Open freelance gigs for freelancers to apply to, newest first. query is
        required. There is no free preview: every call returns full gigs at 5
        credits per new gig (default limit 10); no matches use 0 credits and
        gigs the caller already bought are free, counted in already_purchased. A
        search's results are kept for a few hours, so pages and repeats are
        consistent. A page is released only after an atomic full-page debit is
        confirmed. Sending preview returns 422.
      operationId: searchGigs
      requestBody:
        required: true
        description: 'Send JSON with Content-Type: application/json.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchGigsRequest'
            examples:
              full:
                summary: First page of 3
                value:
                  job_title: full stack developer
                  remote: remote
                  posted_within_days: 7
                  limit: 3
      responses:
        '200':
          description: Success envelope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  result:
                    $ref: '#/components/schemas/GigsPage'
                  message:
                    type: string
                required:
                  - success
                  - result
                  - message
        '400':
          description: >-
            bad_request: malformed JSON, invalid full-search limit, or cursor
            invalid / from different filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'unauthorized: missing, invalid or revoked API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: >-
            insufficient_credits: insufficient balance for the entire page. No
            records returned and no credits deducted; reduce limit or buy
            credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            validation_failed: missing job_title, unsupported country_code,
            unknown field (including preview), or invalid remote, job_type,
            posted_within_days or field length.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            rate_limited: key, account or IP request limit exceeded; wait a
            minute before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 'internal: unexpected server failure.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 'upstream_unavailable: gateway could not reach the service.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            upstream_unavailable: job search, preview counter or billing
            dependency unavailable. No postings are returned; an unconfirmed
            charge may already have debited credits, so inspect usage before
            retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SearchGigsRequest:
      type: object
      additionalProperties: false
      required:
        - query
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 200
          description: >-
            The skill or kind of work, e.g. shopify developer or logo design.
            Required.
        sort:
          type: string
          enum:
            - newest
            - relevance
          default: newest
          description: Newest first (default) or most relevant first.
        budget_type:
          type: string
          enum:
            - hourly
            - fixed
          description: Only hourly or only fixed-price gigs. Omit for both.
        hourly_rate_min:
          type: integer
          minimum: 0
          maximum: 1000000
          description: Lowest hourly rate in USD (hourly gigs).
        hourly_rate_max:
          type: integer
          minimum: 0
          maximum: 1000000
          description: Highest hourly rate in USD (hourly gigs).
        fixed_budget_min:
          type: integer
          minimum: 0
          maximum: 1000000
          description: Lowest fixed budget in USD (fixed-price gigs).
        fixed_budget_max:
          type: integer
          minimum: 0
          maximum: 1000000
          description: Highest fixed budget in USD (fixed-price gigs).
        experience_level:
          anyOf:
            - type: string
            - type: array
              items:
                type: string
              maxItems: 100
          description: entry, intermediate and/or expert.
        project_length:
          anyOf:
            - type: string
            - type: array
              items:
                type: string
              maxItems: 100
          description: under_1_month, 1_to_3_months, 3_to_6_months and/or over_6_months.
        hours_per_week:
          type: string
          enum:
            - part_time
            - full_time
          description: part_time (under 30 hours a week) or full_time (30 or more).
        client_hires:
          anyOf:
            - type: string
            - type: array
              items:
                type: string
              maxItems: 100
          description: 'The client''s hiring history: none, 1_to_9 and/or 10_plus.'
        client_country:
          anyOf:
            - type: string
            - type: array
              items:
                type: string
              maxItems: 100
          description: Clients based in these countries, by English name, e.g. Canada.
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: Gigs to return, 5 credits per new gig.
        cursor:
          type: string
          description: >-
            next_cursor from the previous page; keep every other field
            identical.
    GigsPage:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Gig'
          maxItems: 100
        next_cursor:
          type: string
          description: Opaque continuation token; empty when no next page is available.
        has_more:
          type: boolean
          description: Whether a continuation page is available.
        credits_used:
          type: integer
          minimum: 0
          description: 5 per new gig; gigs already bought and empty pages cost 0.
        already_purchased:
          type: integer
          minimum: 0
          maximum: 100
          description: Gigs the caller bought before; returned without charge.
      required:
        - results
        - next_cursor
        - has_more
        - credits_used
      description: No total_estimate or total_capped fields are returned by public search.
    Error:
      type: object
      properties:
        success:
          type: boolean
          const: false
        result:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
          required:
            - code
        message:
          type: string
          description: Human-readable error; do not parse this as a stable identifier.
      required:
        - success
        - result
        - message
    Gig:
      type: object
      description: >-
        An open freelance gig to apply for. Empty strings, null and [] mean not
        listed.
      properties:
        gig_id:
          type: string
          description: Enricho gig ID.
        title:
          type: string
          description: Gig title.
        description:
          type: string
          description: The client's brief.
        posted_at:
          type: string
          description: When it was posted (RFC 3339, UTC).
        apply_url:
          type: string
          description: >-
            The posting on the freelance marketplace, where the freelancer
            applies with their own account.
        budget:
          type: object
          properties:
            type:
              type: string
              description: fixed or hourly.
            fixed:
              type:
                - number
                - 'null'
              description: Fixed budget.
            hourly_min:
              type:
                - number
                - 'null'
              description: Lowest hourly rate.
            hourly_max:
              type:
                - number
                - 'null'
              description: Highest hourly rate.
            currency:
              type: string
              description: Always USD.
        experience_level:
          type: string
          description: Required experience level.
        project_length:
          type: string
          description: Expected project length.
        hours_per_week:
          type: string
          description: Expected weekly hours.
        project_type:
          type: string
          description: One-time or ongoing.
        category:
          type: string
          description: Category.
        category_group:
          type: string
          description: Category group.
        occupation:
          type: string
          description: Occupation.
        skills:
          type: array
          items:
            type: string
          description: Skills the client asks for.
        contract_to_hire:
          type: boolean
          description: May turn into a hire.
        featured:
          type: boolean
          description: A featured posting.
        positions_to_hire:
          type:
            - integer
            - 'null'
          description: Freelancers the client wants.
        deadline:
          type: string
          description: Deadline, when set.
        activity:
          type: object
          properties:
            applicants:
              type:
                - integer
                - 'null'
              description: Proposals so far.
            interviewing:
              type:
                - integer
                - 'null'
              description: Freelancers being interviewed.
            invites_sent:
              type:
                - integer
                - 'null'
              description: Invitations the client sent.
            hired:
              type:
                - integer
                - 'null'
              description: Freelancers hired.
        client:
          type: object
          properties:
            country:
              type: string
              description: Client country.
            city:
              type: string
              description: Client city.
            timezone:
              type: string
              description: Client timezone.
            industry:
              type: string
              description: Client industry.
            company_size:
              type: string
              description: Client company size.
            rating:
              type:
                - number
                - 'null'
              description: Average rating from freelancers.
            reviews:
              type:
                - integer
                - 'null'
              description: Reviews received.
            total_spent:
              type:
                - number
                - 'null'
              description: Total spent on the marketplace, USD.
            total_hires:
              type:
                - integer
                - 'null'
              description: Freelancers hired.
            jobs_with_hires:
              type:
                - integer
                - 'null'
              description: Postings that led to a hire.
            open_jobs:
              type:
                - integer
                - 'null'
              description: Open postings.
            payment_verified:
              type:
                - boolean
                - 'null'
              description: Payment method verified.
            member_since:
              type: string
              description: YYYY-MM-DD.
            last_seen:
              type: string
              description: Last activity, as the marketplace shows it.
        requirements:
          type: object
          properties:
            english_level:
              type: string
              description: Required English level.
            freelancer_type:
              type: string
              description: Independent or agency, when required.
            min_job_success_score:
              type:
                - integer
                - 'null'
              description: Minimum job success score.
            rising_talent_ok:
              type: boolean
              description: Newer freelancers welcome.
            countries:
              type: array
              items:
                type: string
              description: Required freelancer countries.
            regions:
              type: array
              items:
                type: string
              description: Required regions.
            languages:
              type: array
              items:
                type: string
              description: Required languages.
            timezones:
              type: array
              items:
                type: string
              description: Required timezones.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Enricho API key (enr_...)
    headerKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        An Enricho API key (enr_...). Use this or Authorization: Bearer, not
        both.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.