> ## Documentation Index
> Fetch the complete documentation index at: https://api.tryspecter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create saved search
> Saves an existing query under a name so its results can be read later.
Free. This call does not consume credits.
## What you need
A `query_id`, which [AI search](/api-reference/search/ai-search) returns for every query it resolves, and a name.
## Behaviour
- The product is taken from the saved query, not the request, so a saved search and its filters cannot disagree about which product they describe. Sending a `product_type` is rejected with `422`.
- The search is shared with the API and with your organization on creation, so it appears in [Get all saved searches](/api-reference/saved-searches/get-all-saved-searches) immediately and is visible to your team in the app.
- The search is assigned to an admin of your organization, returned as `owner_id`. You do not choose the owner: only an admin-owned search can be deleted through the API, so any other owner would leave a search you cannot remove. An organization with no admin gets a `422`.
- A name the owner has already used returns `409`.
- An unknown `query_id` returns `404`.
## What you do next
- **Read the results.** Take the returned `id` and call the matching product's results endpoint.
- **Remove it.** Delete it with [Delete search](/api-reference/saved-searches/delete-search).
## OpenAPI
````yaml /api-ref/bundle_api.yaml post /searches
openapi: 3.0.0
info:
title: Specter API
termsOfService: https://tryspecter.com/terms/
contact:
name: API support
email: api-support@tryspecter.com
version: 1.0.0
servers:
- description: Production
url: https://app.tryspecter.com/api/v1
security:
- ApiKeyAuth: []
tags:
- name: Enrich
description: >
Look up a company, person, or investor and, if Specter does not already
hold it, fetch it on demand. Includes email-based person enrichment.
- name: Search
description: |
Find records across every product from a single plain-English query.
- name: Companies
description: >
Company profiles, funding, headcount, traction, the per-company signals
and sub-resources attached to a single company, and identifier resolution.
- name: People
description: >
Specter people records: profile data, contact details, and per-person
lookups for a known person ID.
- name: Investors
description: >
Specter investor records: profile, activity, targeting, funds, portfolio
companies, and the funding rounds they have participated in.
- name: Transactions
description: |
Transaction detail by ID: funding rounds, acquisitions, and IPOs.
- name: Revenue Signals
description: >
Revenue and profitability signals: by ID, by date, and for a saved list or
company search.
- name: Talent Signals
description: |
Talent signals: by ID and in bulk by ID.
- name: Investor Interest Signals
description: |
Investor interest signals: by ID and in bulk by ID.
- name: Company Lists
description: |
Create, query, and maintain lists of companies, including their results.
- name: Investor Lists
description: |
Create, query, and maintain lists of investors, including their results.
- name: People Lists
description: |
Create, query, and maintain lists of people, including their results.
- name: Saved Searches
description: |
List and delete searches saved via tryspecter.com.
- name: Company Saved Searches
description: |
Details and results for saved company searches.
- name: People Saved Searches
description: |
Details and results for saved people searches.
- name: Investor Saved Searches
description: |
Details and results for saved investor searches.
- name: Talent Signals Saved Searches
description: |
Details and results for saved Talent Signals searches.
- name: Investor Interest Saved Searches
description: |
Details and results for saved Investor Interest Signals searches.
- name: Funding Rounds Saved Searches
description: |
Details and results for saved funding-round searches.
- name: Acquisitions Saved Searches
description: |
Details and results for saved acquisition searches.
- name: IPOs Saved Searches
description: |
Details and results for saved IPO searches.
- name: Network
description: >
Your team's LinkedIn network: the people and companies your teammates are
connected to, and your reach into a given company.
- name: Account
description: >
Organisation-level resources: your team's members, API call logs, and
credit balance.
paths:
/searches:
post:
tags:
- Saved Searches
summary: Create saved search
description: >
Saves an existing query under a name so its results can be read later.
Free. This call does not consume credits.
## What you need
A `query_id`, which [AI search](/api-reference/search/ai-search) returns
for every query it resolves, and a name.
## Behaviour
- The product is taken from the saved query, not the request, so a saved
search and its filters cannot disagree about which product they
describe. Sending a `product_type` is rejected with `422`.
- The search is shared with the API and with your organization on
creation, so it appears in [Get all saved
searches](/api-reference/saved-searches/get-all-saved-searches)
immediately and is visible to your team in the app.
- The search is assigned to an admin of your organization, returned as
`owner_id`. You do not choose the owner: only an admin-owned search can
be deleted through the API, so any other owner would leave a search you
cannot remove. An organization with no admin gets a `422`.
- A name the owner has already used returns `409`.
- An unknown `query_id` returns `404`.
## What you do next
- **Read the results.** Take the returned `id` and call the matching
product's results endpoint.
- **Remove it.** Delete it with [Delete
search](/api-reference/saved-searches/delete-search).
operationId: createSavedSearch
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- query_id
- name
additionalProperties: false
properties:
query_id:
type: integer
description: >
Id of the query to save, as returned by [AI
search](/api-reference/search/ai-search).
example: 4242
name:
type: string
minLength: 1
description: Display name for the saved search.
example: German fintech
description:
type: string
nullable: true
description: Optional description for the saved search.
example:
query_id: 4242
name: German fintech
responses:
'201':
description: The saved search that was created.
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: Id of the saved search, for the read endpoints.
example: 41966
name:
type: string
example: German fintech
query_id:
type: integer
example: 4242
product_type:
type: string
description: Product the saved query searches.
example: company
owner_id:
type: string
description: |
Id of the organization admin the search was assigned to.
example: user_2abcDEF456
required:
- id
- name
- query_id
- product_type
- owner_id
additionalProperties: false
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: A saved search with that name already exists for the owner.
'422':
description: >
Your organization has no admin to own the search, or the body
carried an unknown field.
components:
responses:
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ApiKeyMissing'
- $ref: '#/components/schemas/ApiKeyNotValid'
Forbidden:
description: Forbidden - There is no permissions to use the endpoint
content:
application/json:
schema:
type: object
properties:
errorCode:
description: NOT_PERMITTED
type: string
example: NOT_PERMITTED
message:
type: string
description: You do not have permission to access this resource.
example: You do not have permission to access this resource.
required:
- errorCode
- message
NotFound:
description: Not Found
content:
application/json:
schema:
type: object
required:
- errorCode
- message
properties:
errorCode:
type: string
description: NOT_FOUND
message:
type: string
description: Not Found
schemas:
ApiKeyMissing:
properties:
errorCode:
description: API_KEY_MISSING
example: API_KEY_MISSING
type: string
message:
description: No API Key was presented on the header X-API-KEY
example: No API Key was presented on the header X-API-KEY
type: string
ApiKeyNotValid:
properties:
errorCode:
description: API_KEY_NOT_VALID
example: API_KEY_NOT_VALID
type: string
message:
description: API key present, but not valid
example: API key present, but not valid
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
````