> ## Documentation Index > Fetch the complete documentation index at: https://docs.trysignalbase.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a Definition > Create a definition of your own from a name and a plain-English rule. Signalbase compiles the rule into search phrases and a matching rule and test-runs it against recent posts; the definition moves compiling → testing → ready over a few minutes. Poll Retrieve Definition until it is ready, review the test leads, then start it with Update Definition (`active: true`). Nothing is swept until it is started. With `targets` the definition only watches those companies; without, it sweeps every post. Free (0 credits). A team may hold 3 definitions (paused ones count, removed ones do not); the feature needs a Pro plan. ## OpenAPI ````yaml POST /signals/custom/definitions openapi: 3.1.0 info: title: Custom Signals API description: >- Signals produced by custom signal definitions — signal types defined as data (out of stealth, new office or market entry, first or founding hire, …) rather than the four built-in families. One endpoint serves every definition; `type` selects which. A free companion endpoint lists the definitions, and a team can create, start, pause and remove definitions of its own. license: name: MIT version: 2.1.0 servers: - url: https://www.trysignalbase.com/api/v2 security: - bearerAuth: [] paths: /signals/custom/definitions: post: summary: Create a Custom Signal Definition description: >- Create a definition of your own from a name and a plain-English rule. Signalbase compiles the rule into search phrases and a matching rule and test-runs it against recent posts; the definition moves compiling → testing → ready over a few minutes. Poll Retrieve Definition until it is ready, review the test leads, then start it with Update Definition (`active: true`). Nothing is swept until it is started. With `targets` the definition only watches those companies; without, it sweeps every post. Free (0 credits). A team may hold 3 definitions (paused ones count, removed ones do not); the feature needs a Pro plan. operationId: createCustomSignalDefinition requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DefinitionCreateRequest' example: name: First sales leader description: >- The author's own company announces hiring its first sales leader or is building its first sales team: a first VP Sales, Head of Sales, CRO or founding account executive. Exclude ordinary sales hires at companies that already have a sales team, and recruiter posts about other companies. responses: '201': description: Definition created and queued for compilation. content: application/json: schema: $ref: '#/components/schemas/OwnDefinitionResponse' example: success: true data: slug: first_sales_leader_x7k2 name: First sales leader description: '' sourceDescription: >- The author's own company announces hiring its first sales leader or is building its first sales team: a first VP Sales, Head of Sales, CRO or founding account executive. Exclude ordinary sales hires at companies that already have a sales team, and recruiter posts about other companies. status: compiling scope: team attributes: [] keywordCount: 0 restricted: false monitorId: null compileError: null test: null lastRunAt: null lastRunStats: null activatedAt: null createdAt: '2026-11-10T09:12:04.000Z' signals30d: 0 signalsTotal: 0 lastSignalAt: null attached: null nextStep: >- The definition is being compiled into search phrases and a matching rule. Read it again in a minute; it moves to testing, then ready. meta: endpoint: customSignals.create creditsUsed: 0 '400': description: >- Bad request — a malformed body, slug or value; the message names the field content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: You can have 3 custom signals. Remove one to add another. '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Invalid API key '403': description: >- Forbidden — custom signals need a Pro plan, or the team has no active subscription content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Custom signals are part of the Pro plan. '404': description: >- Not found — no definition with this slug belongs to your team (global definitions are not managed here), or custom signals are not enabled for your account yet content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Custom signal not found '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Rate limit exceeded '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Internal server error components: schemas: DefinitionCreateRequest: type: object required: - name - description properties: name: type: string minLength: 3 maxLength: 80 description: >- A short name for the signal, e.g. "First sales leader". The slug is derived from it. description: type: string minLength: 20 maxLength: 1500 description: >- What a post must say for it to count, as a plain-English rule about the author's own company: the event, what makes it that event and not a neighbour of it, and anything to exclude. Two or three sentences. Compiled into search phrases and a matching rule — write the rule, not a keyword list. targets: type: array minItems: 1 maxItems: 100 items: type: string maxLength: 500 description: >- Company website domains or LinkedIn company URLs. Given, the definition only sweeps posts from these companies (a monitor watching the new slug holds them); omitted, it sweeps every post. `companies` is accepted as an alias. OwnDefinitionResponse: type: object properties: success: type: boolean data: $ref: '#/components/schemas/OwnDefinition' meta: $ref: '#/components/schemas/Meta' ErrorResponse: type: object properties: success: type: boolean example: false error: type: string OwnDefinition: type: object description: One of your team's own definitions, as the Custom signals page shows it. properties: slug: type: string description: >- Derived from the name and made unique with a short suffix. Pass it as `type` on GET /signals/custom or in a monitor's signal_types. name: type: string description: type: string description: >- The compiled rule a post must satisfy. Written by the compile step from sourceDescription; empty until compiled. sourceDescription: type: - string - 'null' description: What you sent as `description` when creating it. status: type: string enum: - compiling - testing - ready - active - paused - disabled - failed description: >- compiling: search phrases and a rule are being derived. testing: a test run is in flight. ready: tested, not started; review test.leads. active: running. paused: kept, not swept. failed: see compileError. disabled: removed. scope: type: string enum: - team attributes: type: array items: type: string description: >- The definition-specific fields its signals carry (set by the compile step). keywordCount: type: integer description: How many search phrases the compile step produced. restricted: type: boolean description: >- true when the definition only sweeps its targets' posts (through a monitor). monitorId: type: - string - 'null' description: The monitor that holds the targets of a restricted definition. compileError: type: - string - 'null' test: oneOf: - $ref: '#/components/schemas/TestRun' - type: 'null' lastRunAt: type: - string - 'null' format: date-time description: When the sweep last ran this definition. lastRunStats: type: - object - 'null' additionalProperties: true activatedAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time signals30d: type: integer signalsTotal: type: integer lastSignalAt: type: - string - 'null' format: date-time nextStep: type: string description: What to do next, given the status. attached: type: - object - 'null' description: >- Create only: how the targets resolved. null when the definition is global. properties: companies: type: integer invalid: type: array items: type: string seeded: type: object description: >- Update with active:true, first start only: how many test leads became signals. properties: ingested: type: integer skipped: type: integer Meta: type: object properties: endpoint: type: string creditsUsed: type: integer creditsRemaining: type: integer TestRun: type: object description: >- The last test run: how many recent posts were fetched and classified, how many matched, and the matches themselves. properties: ranAt: type: - string - 'null' format: date-time mode: type: string enum: - global - restricted description: restricted when the definition has targets. fetched: type: integer classified: type: integer matched: type: integer companiesChecked: type: integer description: 'Restricted runs only: how many of the targets were checked.' leads: type: array items: $ref: '#/components/schemas/TestLead' TestLead: type: object description: >- One post the test run matched. The leads of a ready definition become its first signals when it is started. properties: companyName: type: - string - 'null' companyLinkedinUrl: type: - string - 'null' headline: type: - string - 'null' description: The event, stated as a fact. confidence: type: - number - 'null' minimum: 0 maximum: 1 sourceUrl: type: string description: The post. author: type: - string - 'null' evidenceQuotes: type: array items: type: string description: Verbatim from the post. attributes: type: object additionalProperties: type: - string - 'null' postedAt: type: - string - 'null' format: date-time securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: API key authentication. Include as Bearer token in Authorization header. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.