{
 "openapi": "3.1.0",
 "info": {
  "title": "Nava API",
  "version": "0.1.0",
  "description": "Find real UGC creators who are a brand's customer, checked from their own bio and posts. The same tools are on the MCP server at https://meetnava.com/mcp. A search usually takes 1-2 minutes; GET /searches/{job_id}?wait_seconds=45 waits for it. Free: 5 creators per email in all; Solo and Pro searches start once paid. TikTok only for now."
 },
 "servers": [
  {
   "url": "https://meetnava.com/api/v1"
  }
 ],
 "paths": {
  "/estimate": {
   "post": {
    "operationId": "estimate",
    "summary": "Preview a search: how the brief is read, what counts, typical yield, time and price. Free; stores nothing.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "who": {
          "type": "string",
          "description": "Who the creators should be, in plain words, e.g. \"ER nurses who work nights\"."
         },
         "must": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "description": "Requirements every match must show. Default: everything in who."
         },
         "nice": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "description": "Preferences that rank a creator higher but aren't required."
         },
         "platforms": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "description": "Only \"tiktok\" for now."
         },
         "followers": {
          "type": "object",
          "properties": {
           "min": {
            "type": "integer"
           },
           "max": {
            "type": "integer"
           }
          },
          "description": "Default 1,000 to 150,000."
         },
         "country": {
          "type": "string"
         },
         "brand": {
          "type": "string"
         },
         "product_url": {
          "type": "string"
         },
         "notes": {
          "type": "string"
         }
        },
        "required": [
         "who"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "The preview"
     },
     "400": {
      "description": "What to change",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/searches": {
   "post": {
    "operationId": "find_creators",
    "summary": "Start a creator search. Returns instant matches from creators Nava already checked, plus a job id; graded matches arrive within a day.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "who": {
          "type": "string",
          "description": "Who the creators should be, in plain words, e.g. \"ER nurses who work nights\"."
         },
         "must": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "description": "Requirements every match must show. Default: everything in who."
         },
         "nice": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "description": "Preferences that rank a creator higher but aren't required."
         },
         "platforms": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "description": "Only \"tiktok\" for now."
         },
         "followers": {
          "type": "object",
          "properties": {
           "min": {
            "type": "integer"
           },
           "max": {
            "type": "integer"
           }
          },
          "description": "Default 1,000 to 150,000."
         },
         "country": {
          "type": "string"
         },
         "brand": {
          "type": "string"
         },
         "product_url": {
          "type": "string"
         },
         "notes": {
          "type": "string"
         },
         "contact_email": {
          "type": "string"
         },
         "plan": {
          "type": "string",
          "enum": [
           "free",
           "solo",
           "pro"
          ],
          "description": "free (default): 5 creators per email in all. solo ($27/month) and pro ($97/month): Nava emails a payment link and the search starts once it's paid."
         },
         "max_matches": {
          "type": "integer"
         }
        },
        "required": [
         "who",
         "contact_email"
        ]
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Queued",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "job_id": {
           "type": "string"
          },
          "status": {
           "type": "string"
          },
          "max_matches": {
           "type": "integer"
          },
          "next": {
           "type": "string"
          },
          "instant_matches": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "handle": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "platform": {
              "type": "string"
             },
             "url": {
              "type": "string"
             },
             "fit": {
              "type": "string"
             },
             "who": {
              "type": "string"
             },
             "why": {
              "type": "string"
             },
             "followers": {
              "type": "integer"
             },
             "typical_views": {
              "type": "number"
             },
             "views_to_followers": {
              "type": "number"
             },
             "last_post_days": {
              "type": "number"
             },
             "best_video": {
              "type": "string"
             },
             "contact": {
              "type": "string"
             },
             "checked_for": {
              "type": "string"
             },
             "matched_on": {
              "type": "array",
              "items": {
               "type": "string"
              }
             }
            }
           },
           "description": "Creators Nava already checked for an earlier brief that look like this one; not yet graded against this brief's must-haves."
          },
          "instant_note": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "What to change",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "What to change",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/searches/{job_id}": {
   "get": {
    "operationId": "get_job",
    "summary": "Status and results of a search.",
    "parameters": [
     {
      "name": "job_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "wait_seconds",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 0,
       "maximum": 50,
       "default": 0
      },
      "description": "Wait up to this many seconds for a running search to finish before answering. Searches usually take 1-2 minutes."
     }
    ],
    "responses": {
     "200": {
      "description": "The search",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "string"
          },
          "status": {
           "type": "string",
           "enum": [
            "awaiting_payment",
            "queued",
            "running",
            "done",
            "failed"
           ]
          },
          "who": {
           "type": "string"
          },
          "matches": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "handle": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "platform": {
              "type": "string"
             },
             "url": {
              "type": "string"
             },
             "fit": {
              "type": "string"
             },
             "who": {
              "type": "string"
             },
             "why": {
              "type": "string"
             },
             "followers": {
              "type": "integer"
             },
             "typical_views": {
              "type": "number"
             },
             "views_to_followers": {
              "type": "number"
             },
             "last_post_days": {
              "type": "number"
             },
             "best_video": {
              "type": "string"
             },
             "contact": {
              "type": "string"
             },
             "evidence": {
              "type": "array",
              "description": "One entry per must-have, in the brief's order.",
              "items": {
               "type": "object",
               "properties": {
                "must": {
                 "type": "string"
                },
                "type": {
                 "type": "string",
                 "enum": [
                  "role",
                  "credential",
                  "place",
                  "life_stage",
                  "condition",
                  "event",
                  "behavior",
                  "demographic",
                  "unobservable"
                 ]
                },
                "verdict": {
                 "type": "string",
                 "enum": [
                  "yes",
                  "unverifiable"
                 ],
                 "description": "Every judged must-have of a match is yes; unverifiable means public posts can't show it."
                },
                "quote": {
                 "type": "string",
                 "description": "The line from their bio or a caption that shows it."
                },
                "url": {
                 "type": "string",
                 "description": "For an event: the post that shows it."
                },
                "days_ago": {
                 "type": "integer"
                },
                "weak_evidence": {
                 "type": "boolean"
                },
                "judged_by_proxy": {
                 "type": "string"
                }
               }
              }
             },
             "source": {
              "type": "string",
              "description": "index, index, regraded, index, refreshed or search"
             }
            }
           }
          },
          "funnel": {
           "type": "object"
          },
          "message": {
           "type": "string"
          },
          "found": {
           "type": "integer",
           "description": "Exact fits found in total; matches holds at most max_matches of them."
          },
          "read_as": {
           "type": "object",
           "description": "The typed reading of the brief: musts[] with type, window_days, event_regex, observable, proxy; collisions[]; unverifiable[]."
          },
          "cost": {
           "type": "object",
           "description": "What this search cost Nava: data_usd, ai_usd, total_usd, per_match_usd, calls."
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "What to change",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/outreach": {
   "post": {
    "operationId": "request_outreach",
    "summary": "Done for you: Nava contacts creators and returns who said yes, with rates. A person replies with a quote within a day.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "who": {
          "type": "string",
          "description": "Who the creators should be, in plain words, e.g. \"ER nurses who work nights\"."
         },
         "must": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "description": "Requirements every match must show. Default: everything in who."
         },
         "nice": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "description": "Preferences that rank a creator higher but aren't required."
         },
         "platforms": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "description": "Only \"tiktok\" for now."
         },
         "followers": {
          "type": "object",
          "properties": {
           "min": {
            "type": "integer"
           },
           "max": {
            "type": "integer"
           }
          },
          "description": "Default 1,000 to 150,000."
         },
         "country": {
          "type": "string"
         },
         "brand": {
          "type": "string"
         },
         "product_url": {
          "type": "string"
         },
         "notes": {
          "type": "string"
         },
         "contact_email": {
          "type": "string"
         },
         "budget": {
          "type": "string"
         },
         "timeline": {
          "type": "string"
         },
         "deliverables": {
          "type": "string"
         },
         "job_id": {
          "type": "string"
         },
         "creator_handles": {
          "type": "array",
          "items": {
           "type": "string"
          }
         }
        },
        "required": [
         "who",
         "contact_email",
         "budget",
         "timeline"
        ]
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Received"
     },
     "400": {
      "description": "What to change",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "What to change",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/outreach/{request_id}": {
   "get": {
    "operationId": "get_request",
    "summary": "Status of an outreach request and Nava's latest message.",
    "parameters": [
     {
      "name": "request_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The request"
     },
     "404": {
      "description": "What to change",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  }
 }
}